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PREFACE 



The OS/ 16 MT2 Multi-Tasking Operating System provides an efficient means for using INTERDATA 16-Bit Processors. Its 
ease of use, servicability and efficient resource management allow the user to concentrate on problem solving rather than 
system management. 

This manual is intended for use as a programming reference manual. Chapter 1 describes the system in general terms. 
Chapter 2 provides information on task control at the program level. Chapter 3 describes the Supervisor Call (SVC) 
instructions supported by OS/ 16 MT2. Chapters 4, 5, 6, and 7 provide introductory guides to the use of SVC 2 facilities, 
task handled traps, Direct Access files, and user task overlays. Chapter 8 provides detailed device dependent information 
for I/O programming. 

The three Appendices include an SVC Summary, a Control Block Summary, and OS/16 MT2 Data Structures. 

OS/ 16 MT2 is a multi-tasking Operating System designed for INTERDATA 16-Bit Architecture Processors. The user should 
be familiar with the information in the following documents: 

16-Bit Processor User's Manual, Publication Number 29-509 

This manual is intended as a programming reference manual for OS/16 MT2. For information on operating OS/16 MT2 
refer to: 

0SI16 MT2 Operator's Manual, Publication Number 29-430 

Other manuals related to OS/16 MT2 are; 

OS/ 1 6 MT2 System Planning and Configuration Guide, Publicafion Number 29-431 

OS/16 MT2 Pocket Guide, Publication Number 29-433 

OS/16 MT2 Program Logic Manual, Publication Number 29-434 
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CHAPTER 1 
SYSTEM OVERVIEW 



INTRODUCTION 



The OS/ 16 MT2 Multi-Tasking Operating System provides an efficient and powerful means for using the resources of an 
INTERDATA 16-Bit Processor and its environment. Through easy to use services and efficient resource management, the 
user is free to concentrate on problem solving rather than on system management. OS/16 MT2 provides: 



System control services through the Command Processor. 

Program control services through the Task Management Facilities of the Executive. 

Memory management through the Executive. 

Direct Access and Non-direct Access data management services through the File Manager and Device 
Drivers. 



Figure 1-1 illustrates the components of OS/ 16 MT2 and their relationships. 

System control is supported both from the system console and from user specified files or devices. The OS/ 16 MT2 
Command language may be extended through the facilities of the Command Substitution System (CSS) to allow invoca- 
tion of complex control sequences with a single command. 

Program control support includes, background and foreground facilities so that program preparation can proceed con- 
currently with real-time system operation. Intertask communication, task handled traps, single tasking, multi-tasking and 
parallel tasking support is provided. 

Memory management facilities include multiple task common areas and resident library partitions, and multiple overlay 
area capabilities for user tasks.. Storage management services are provided by the Executive for orderly memory 
management by user tasks. Foreground tasks are protected from undebugged background tasks. User space is divided into 
partitions established at system generation time. Partition sizes can be changed dynamically by the system operator. 

The OS/ 1 6 MT2 File Manager and Device Drivers provide a powerful set of data management services for both Direct 
Access and non-Direct Access devices. Two types of Direct Access file organization are supported: Contiguous and 
Indexed. Both static and dynamic protection is provided for I/O devices and Direct Access files. 
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Figure 1-1. OS/ 16 MT2 System Overview 
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The OS/16 MT2 user can access the facilities of the system througli either of two interfaces: 

1. Operator interface; provided by the command language of the OS/16 MT2 Command Processor. 

2. Program interface; provided by Supervisor Call (SVC) instructions serviced by the OS/ 16 MT2 
Executive and File Manager. 

In order to provide powerful facilities in the most efficient manner, an OS/ 16 MT2 System can be tailored to a specific 
hardware and system environment through the OS/ 16 MT2 system generation (SYSGEN) procedure. In addition, non- 
critical portions of the Operating System mfiy be maintained on a Disc and brought into memory only when necessary, 
greatly reducing the memory requirements of the system. " ' ' 

OS/16 MT2 can function as a subset of OS/32 MT for applications programming. Indexed and Contiguous Disc files are 
compatible between OS/ 16 MT2 and OS/32 MT. 



SYSTEM DESCRIPTION 

Tasks 

Program control services are provided for controlling a single task or a complex system of tasks. A task may consist of a 
single program, or it may include a main program with a number of subroutines and overlays. Tasks may be permanently 
resident in memory, or they may be loaded as required. Tasks are referred to by a Task Identifier (TASKID) which is 
associated with the task at load time.. The riumber of tasks allowed in memory at one time is limited only by the number of 
partitions established at system generation time. 

The following sections describe two pairs of task categorizations. 

Foreground/Background Tasks 

Tasks resident in a foreground memory partition are referred to as foreground tasks while a task resident in the background 
partition is referred to as the background task. Foreground tasks have the full range of OS/ 16 MT2 services available while 
a background task has the following restrictions: 

Intertask communication facilities are not supported. 

Task priority is under console operator control. 

A background task may not communicate with the foreground tasks through Task Common. 

This prevents a background task from interfering with the foreground system, thus providing a safe environment for task 
debugging. 

Tasks may be established as tasks Dy processing the main program and any subroutines or overlays with the OS/ 16. Task 
Establisher Task (TET/16). The output of TET/16 may then be loaded by a foreground task or by an operator command. 
tET/16 output consists of a record which contains the Loader Information Block (LIB) followed by records which contain 
a memory image of the established task. The LIB contains information needed by the\resideii1; linage loaden to ensure 
proper loading of the task. 

Alternatively, a task may be loaded directly in object format (output of CAL — the INTERDATA Common Assembler) by 
the background or the foreground object load operator commands, if it consists of a single program, or after processing by 
the OS/ 16 Library Loader, if it consists of multiple programs and subroutines. 

User/Executive Tasks 

At task establishnvent time,, a task may be designated as a User task or an Executive task. User tasks (U-tasks) run in a 
protected mode while Executive tasks (E-tasks) have the full range of 16-bit architecture canabilities available. E-tasks 
capaoilities are designed to provide an oroerly and well defined means for adding system extensions. 

Previously Written 16-bit programs 

Programs written for previous operating systems (BOSS, DOS, or RTOS) must run with the compatibility option, due to 
differences in the SVC 1 and SVC 5 parameter blocks. See the OSI16MT2 Operator's Manual. 
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Program Addresses and Logical Segments 

The process of establishing a user task via TET/16 produces a memory image load module of the task. This means the task 
may be loaded by simply reading it into the appropriate memoiy partition. At assembly time, whether the task consists of 
assembly language programs or FORTRAN output, the program references data and instructions using program addresses 
which are usually relative to the first location of the task. At task establish time, these addresses are converted to addresses 
within the partition that the task is being established for, or to addresses within the specified task common or hbrary 
partition (see Chapter 5 of the OS/16 MT2 Operator's Manual for task establishment procedures). Thus an established task 
can contain references to several disjoint ranges of contiguous addresses: addresses in the program's partition, those in a 
task common partition, and tliose in a library partition. Each range of contiguous addresses is termed a Logical Segment. 
The three possible logical segment types are: 

Program Segment 
Library Segment 
Task Common Segment 

Status 

A task in memory may be in any of five states. These are: 

Current 

Ready 

Wait 

Paused 

Dormant 

The Current task is the one executing instnictions. Only one task may be in this state at any given instant in time. All other 
tasks in memory are in one of the other four states, but may become the Current task depending on circumstances. 

A Ready task is one which has no obstacles to becoming the Current task. It is eligible to be scheduled (i.e., become 
Current) whenever it becomes the highest priority Ready task. 

A task in Wait state is one which may not become Ready until some specific circumstance has occurred. Among the 
possible wait states are: 

I/O Wait Waiting for I/O completion 

Time Wait Waiting for an interval or time of day 

Trap Wait Waiting for a task-handled trap 

SVC Wait Waiting for an SVC executor 

A Paused task is one which may not execute until it is explicitly continued by the console operator. A Paused task is said 
to be in Console Wait. 

A Dormant task is one which may not execute until it has been explicitly started, either by the console operator or another 
task. When a resident task goes to End of Task (EOT), it enters the Dormant state. When any task is loaded, it enters the 
Dormant state after loading is complete, and remains in this state until it is started. 

Paused and Dormant are both Wait states; they are listed separately since they require operator intervention. 

Protection 

User tasks run in a protected mode. This means that they cannot use any privileged instruction. Privileged instructions 
include all I/O instructions and any instruction that changes the state of the Processor, such as LPSW, EPSR. 

In order to request I/O functions or any Processor state change, user tasks must use a Supervisor Call (SVC) instruction. 

Command Processor Services 

In OS/ 16 MT2, the console operator interface is provided by a task called the Command Processor. The Command 
Processor is an E-task which runs as the highest priority task in the system. All commands are Interpreted and executed by 
the Command Processor which also performs all I/O requests to the console device. The OS/ 16 MT2 Operators Manual 
describes in detail the commands and procedures related to the Command Processor. The Command Processor task is 
included as a part of OS/ 16 MT2 and cannot be cancelled. When the Command Processor is the only task in the system (if 
there is a background task it must be Dormant), the system is said to be quiescent. 
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The Command Processor includes: 

Support for controlling the user memory partitions. 

Command Substitution System (CSS) support which allows the OS/ 16 MT2 operator command language to 
be extended by user defined command sequences. 

Support for controlling I/O devices configured in the system. 
The object loaders which allow tasks to be loaded into memory. 

The Command Processor module can be deleted from the system at system generation. Planning and programming for such 
systems is fully described in Chapter 2 of 08/16 MT2 System Planning and Configuration Guide. 

Memory Management 

Memory in an OS/ 1 6 MT2 system is separated into two classes : 

User space 
System space 

System space is discussed later. User space is divided into partitions. The maximum number of partitions is established at 
system generation time. The console operator may vary the sizes of the partitions when there is no task in an affected 
partition. OS/ 16 MT2 supports four types of partitions: 

Foreground 
Background 
Task Common 
Resident Library 

Foreground Partitions 

Up to 1 25 foreground partitions may be estabUshed at system generation time. Their size is set by operator command. 
When an established task is loaded by the console operator or by another foreground task, it is loaded into the partition 
associated with that task at establishihent time. 

Foreground tasks are permitted to request the loading and execution of other tasks, cancel these tasks or delete them from 
memory, or to pass^arameters'.to other foreground tasks. In operator commands, a foreground partition is referrenced by 
the TASK ID of the task loaded in it or by its partition number, if it is vacant. 

Background Partition 

OS/ 16 MT2 provides png background partition. Intertask service requests are treated as illegal or ignored (depending on the 
task option selected) when execirtedfrom the- background task; therefore the background task may not directly affect the 
operation of any foreground task. A task in the background partition may not use Task Common nor make use of a 
resident Ubrary. ■^ 

The size of the background partition is adjusted by the console operator when the start of the first foreground partition's 
adjusted. The size of the background is set to the -memory between the top of the system and the first foreground 
partition. The background partition is always referenced by its name, .EG. 

Task Common 

A Task Common partition is a sharableforegrgund data partition and, as such, is accessible only to foreground tasks. 
OS/16 MT2 supports multiple Task Common Partitions. When a task is to use a Task Common partition, the user must 
specify the start address of the desired Task Common partition when establishing the task. At task execution time, the 
Task Common partition may be vacant, or it may be initialized by loading a task which defines the desired values. 
Although any task can reference only one Task Common partition, there can be several groups of tasks, each group 
referencing a different Task Common. 

Resident Libraries 

A resident library partition is a foreground partition containing sharable,_reeji^rant_roui^ Multiple resident library 
partitions are supported by OS/16 MT2, although any task can reference only one resident library parti ti on. ^All references 
to routines in.^brary seginent are. resolved at toJL£Stablishment time. A resident library is essentially the same as any 
foreground task; it is loaded and deleted m the same manner. Background tasks that are established by TET/16 can not use 
foreground library partitions. 
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System Space 

Certain memory areas in an OS/16 MT2 system are not occupied by any partition. These areas are known as system space. 
System space is used in OS/ 16 MT2 for two purposes: to hold the OS/ 16 MT2 code itself, and to hold certain tables and 
system data structures required for proper operation of the system and of the user tasks. 

The OS itself and all static data structures (those that do not change in size during system execution) are located in the 
lowest part of physical memory, below the background partition. Dynamic data structures, such as File Control Blocks 
(FCBs) are located in the highest part of physical memory. These are the only two areas of system space; the remainder of 
physical memory is devoted to partitions. 

Sample Memory Allocation 

Figure 1-2 is a map of a hypothetical OS/16 MT2 system. The assumed configuration is a Processor with 64KB of memory. 
The OS is presumed to occupy 20KB. The partitions are as follows: 

Task Common: 1KB 

Foreground: 2x4KB, 10KB 

Resident Library: 2KB 

Background: 16KB 

The remaining 7KB is system space. 



Memory Address (Hex) 



10000 




(7KB) '^ 


System Space 


E400 / 

J 


Foreground Partition 5 


(1KB) - 


(Tasl< Common) 


EOOO 






Foreground Partition 4 


(16KB) 




B800 






Foreground Partition 3 


(4KB) 




A800 

J 


Foreground Partition 2 


(2KB) 


(Resident Library) 


AOOO 




-^ 


Foreground Partition 1 


(4KB) 




9000 






Background Partition 


(16KB) 




5000 






OS/ 16 MT2 



Figure 1-2. OS/ 16 MT2 Memory Map Example 
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Resident Loaders - 

OS/16 MT2 provides tiiree resident loaders: the memory image loader and the object format background and foreground 
loaders. 

The memory image loader loads overlays, Task Common segments, resident library segments, and either foreground or 
background tasks. Since this loader loads memory image format, the task to be loaded must have been prepared with 
OS/ 16 Task Establisher Task. The image loader may be invoked, by a foreground task or by operator command. Tliis loader 
performs all functions as a subroutine of the calling task and it is interruptable but not reentrant. That is, higher priority 
tasks are not blocked by the loader but only one task can use the loader at a time. If the loader is in use at the time of a 
loader request, the invoking task is placed in a SVC 6 Wait state. 

The object format loaders load tasks jn 'pbject format (e.g., CAL or OS/16 Library Loader output) and are invoked by 
operator comm'and. '^ 

Roll Out/In 

OS/16 MT2 provides one level of automatic roll out for partitions in a Disc-based OS/16 MT2 system. At the time the 
partitions are established by the operator via the SET PARTITION command, a Contiguous file is allocated for each 
partition on the specified ROLL volume. On a memory image load request, if a task'iFto be loaded into a partition which 
already contains a lower priority task with the roUable option, the lower priority task is rolled out by writing the memory 
image of the partition to the allocated roll file, along with the necessary control information to restart the task. When the 
higher priority task is deleted from the system, the rolled out task is rolled in and it resumes execution from the point of 
interruption. A task is rolled out by a load request only if: 

it has the roUable task option set 
' it is lower priority than the task being loaded 
there is no task rolled out from the specified partition 
there is no incomplete time interval for the task 
.the task is not connected to a Trap Generating Device 

If any of the above conditions are not met, the load request is rejected. While a task is rolled out, no other task can com- 
municate with it. 

Protection 

Memory protection is achieved through the use of the Memory Protect Controller (MPC) which is optional in OS/ 16 MT2. 
Through the MPC, system space is protected against modification during user task execution and foreground partitions are 
protected against rnodification by an undebugged background task. Foreground tasks are allowed to communicate directly 
with each other. In addition, the Supervisor Call (SVC) handler prevents modification of memory outside a user task's 
allocation througli a request for OS/ 16 MT2 services. 

Task Overlays 

To provide more efficient use of memory, OS/16 MT2 supports multiple overlay capabilities for user tasks. At task 
establishment time, the user may organize a task so that only those portions of the task that are necessary are in memory 
at any given time. The remainder of the task can he maintained on a device or file until needed. Task establishment 
facilities, and access to the memory image loader for overlay loading at run time, provide the ability to tailor the memory 
requirements of a task. Multiple overlay areas may^ be defined within the task's memory allocation and any number of 
overlay segments may be^oaded into -each areaas needed, substantially reducing the amount of memory needed to run the 
task. 

Executive Services 

The OS/ 1 6 MT2 Executive provides control over, and extensions to, an INTERDATA 16-Bit Processor as well as providing 
task management facilities. All requests for OS/16 MT2 services are mediated by the Executive's Supervisor Call (SVC) 
handler. Other support provided by the Executive includes: 

Software emulation of Single and Double Precision Floating Point, Multiply and Divide, and List Instruc- 
tions for processors that lack them. 

Support of Line Frequency and Precision Interval Clocks. 

Internal interrupt handling including Power Fail/Restore handling. 

Task scheduling and trap facilities. 

External interrupt handling. 

Support via Supervisor Call (SVC) for most Command Processor services. 
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Interrupts and Traps 

In OS/16 MT2, as in most operating systems, all interrupts at the Processor level, both external and internal, are handled 
by the operating system. OS/16 MT2 provides an interrupt facility at the task level known as the task-handled frap facility. 
This facility permits a task to be interrupted from its normal execution sequence for any one of a variety of causes, both 
hardware and software-generated. This facility also allows one foreground task to pass a parameter to another foreground 
task via the receiving task's Task Queue, thus permitting the receiving task to determine the software defined reason for the 
interrupt. A task handled trap may occur for the following reasons: 

Power Restoration 

Addition of an item to the Task Queue 

Completion of an I/O proceed request 

External Interrupt from a Trap Generating Device 

Completion of a specified time delay 

Message received from another task 

Task Status Word (TSW) 

Traps, and additions to a task's Task Queue are controlled through the task's Task Status Word (TSW), which is the task 
level analog of the 16-Bit Processor Program Status Word (PSW). This status word is used to enable or disable the various 
traps, enable or disable additions to the Task Queue, and to save the location counter and condition code of a task at the 
time of a trap. 

Task-Handled Traps 

The user task can enable or disable the various traps through manipulation of its Task Status Word; on the other hand, a 
user may ignore the task trap facility by choosing the default TSW at task establishment time. The following sections 
briefly discuss the various task-handled trap facilities. 

Task Queue Service 

OS/16 MT2 supports a Task Queue, which is a circular list in standard INTERDATA list processing format, that may be 
associated with a task. If enabled by its Task Status Word (TSW), the following conditions cause an item to be added to a 
task's Task Queue: 

Queuing of an item by another task 

Completion of an 1/0 proceed request 

External Interrupt from a Trap Generating Device such as the Eight-Line Interrupt module. 

Completion of a time interval 

Message received from another task 

Power Restoration 

A task can request a trap, through its TSW, on completion of the system power restoration sequence, instead of being 
paused as is the default action. Any I/O in progress has been aborted by the system prior to the trap, except for Direct 
Access I/O which has been retried. If a task has real-tjme considerations, power restore may indicate that an appreciable 
amount of time has elapsed while power was down. A Power Restoration trap may be used to re-establish time intervals or 
to retreat to a checkpoint for resumption of task execution in an orderly fashion. 

Interrupts 

The OS/ 16 MT2 Executive handles the following Processor internal interrupts and OS/ 16 MT2 generated interrupts in 
essentially the same way: 

Floating Point Arithmetic Fault (Processor) 

Fixed Point Divide Arithmetic Fault (Processor) 

Illegal Instruction (Processor) 

Memory Parity Error (Processor) 

Memory Protect Fault (Processor) 

Illegal SVC (OS/ 1 6 MT2) 

Illegal Address in SVC (OS/16 MT2) 

On detection of any of these faults, default system action is to log a message to the system console and pause the current 
task. Ifjio^ task is curreiit (the. fault occurs during system code execution), a system crash occurs. If the optional system 
crash handler Is included during system gerieratibn, a descriptive crash code is displayed on the display panel and the 
Processor placed in the Wait state. The user task can override default system action for Arithmetic Faults by either 
disabling them or causing the system to simply log a message and continue. 
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Task Priority and Scheduling 

OS/16 MT2 recognizes 256 task priorities from ahigh of to a low of 255. Of these levels, 10 through 249 are available to 
user tasks while through 9 and 250 through 255 are reserved for system use. Task priority is set mitially at task 
•esfablishment time; it may be altered dynamically by another foreground task or 'the operator, up to a maximum set at 
task establishment. 

In OS/1 6 MT2, tasks are scheduled in priority order. Care should be taken in assigning priorities so that tasks which do not 
relinquish control of the Processor do not prevent lower priority tasks from executing. Tasks on the same priority level are 
selected for scheduling according to either of two rules selected at system generation time: 

1. Tasks residing in lower partition chosen ahead of tasks in higher partition (i.e. Task in partition 1 
scheduled ahead of task in partition 2). 

2. Round-Robin scheduling. The most recently scheduled task on the current highest priority level is 
selected for scheduling after all other tasks on the same level. In this scheme, a queue is kept of ready 
tasks ordered by priority. When a task relinquishes control of the system it is placed at the end of its 
priority queue. 

A task relinquishes control of the Processor in any of the following events: 
It is Paused by the console operator 
It is Cancelled 

A higher priority task becomes ready because of an external event. 
It Executes a request for an OS/16 MT2 service which places it in a Paused, Wait, or Dormant state. 

■nUata Management Services 

In order to provide device independent input/output programming, programs direct all I/O requests to a Logical Unit (LU) 
number instead of to a specific device or file. The system maintains a Logical Unit Table (LTAB) for each task. LU 
numbers, which range from zero to a Umit set at system generation time (maximum 63), correspond to LTAB entries for 
the task. The LUs referenced by a task must be assigned to the Specific devices or files by the operator or by the task prior 
to their use. This allows different devices and files to be used without program recompilation. 

Devices 

Input/Output support of peripheral devices such as card readers, line printers, etc. is provided by the various Device 
Drivers. This support is provided to enable a program to be written so that any device supporting the necessary operations 
may be used. Most drivers also provide Support for device dependent operation so that special features and capabilities of 
the device may be used. In general Direct Access Files and peripheral devices may be accessed compatibly. Devices are 
referenced by a device mnemonic which is initially specified at system generation time. This name can be changed 
dynamically by the console operator or by an Executive Task (E-task). 

Direct Access Files 

All direct-access devices supported by OS/16 MT2 may be accessed through the OS/16 File Manager, which provides a 
substantial and powerful set of Volume and file management services. 

Data on a direct-access device is maintained as files on a named logical volume in a compatible manner with OS/32. Each 
volume contains all the information necessary to process the data on that volume. While a direct-access device is marked 
off-line, it is referred to by the device mnemonic associated with the device at system generation time. When a direct-access 
device is marked on-line, the name of the volume mounted on that device is associated with the device and used to refer to 
it. Volumes must not be dismounted without marking the device off-line. 

Before using a direct-access volume, it must be formatted by the Common Disc Formatter, program number 06-1 73, or the 
Common MSM Disc Formatter, program number 06-201, and initiaUzed for OS/ 16 use by the OS/ 16 MT2 INITIALIZE 
operator command. 

Volume Organization 

Allocation of space on an OS/ 16 volume is made in a flexible way, in order to reduce the adverse effects of any defective 
sectors. Only one sector is specifically required to be valid; this is Sector 0, Cylinder 0. On this sector the system maintains 
the Volume Descriptor. All other structures on the disc are allocated by the system wherever feasible. 
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I The Volume Descriptor consists of three fields: 

Volume Name 

Pointer to File Directory 

Pointer to Allocation Map 

I The remainder of the Volume Descriptor is reserved. 

Volume Name field contains a one to four-character ASCII volume identifier. This is the name by which the volume is 
known to the system. 

Pointer to File Directory and Pointer to Allocation Map fields point to the first sectors of the File Directory and 
Allocation Map, respectively. 

All data is initially placed in the Volume Descriptor by the OS/16 INITIALIZE command. 

The Allocation Map is a bit-map having one bit for each sector on the volume., Since a sector occupies 256 bytes, the 
bit-map overhead is only 0.05% of the space on the volume. This map is used only to record allpcated, unallocated and 
defective sectors. If a sector is allocated or defective, its corresponding bit in the Allocation Map is set to ONE; if 
unallocated, to ZERO. 

The File Directory contains information needed by the system to process files recorded on the volume. An entry in the 
directory is made for each file. 

The directory itself is organized as a chain of one-sector blocks. A directory block contains up to five file entries. 

When a direct-access volume is initialized, a number of File Directory blocks are pre-allocated. When the first file on the 
volume is allocated, the first file entry in the directory is then marked as in use and the remaining four as not in use. As 
new directory blocks are needed, they are chained to the end of the File Directory. 

Identification of Files 

An OS/ 16 file is identified by a File Descriptor, which has three parts: volume name, file name, and extension. 

The volume name is composed of from one to four alphanumeric characters, of which the first character must be 
I alphabetic. 

The filename consists of from one to eight alphanumeric characters, of which the first must be alphabetic. This is the main 
identifier for the file, and may be anything the user chooses. 

The extension consists of up to three alphanumeric characters. It may consist of no characters at all, in which case it is 
considered to consist of blanks. The extension usually denotes the type of material on the file. It may be anything the user 
chooses; however, some specific extensions are used by OS/ 16 and by some OS utilities, and are assumed to have specific 
meanings. These extensions are: 

OBJ Absolute or Relocatable loader format 

FTN FORTRAN source format 

CAL CAL assembly language source format 

BAS BASIC source format 

CSS Command Substitution System source format 

TSK Task Image format 

ROL System roll file 

MAC CAL Macro source format 

The user may use any of these standard extensions, or may define others. 



1-10 29-429 ROS 12/78 



File Descriptors are written as follows: 

VOLN:FlLENAME.EXT 

where VOLN is the volume name, FILENAME is the file name, and EXT is the extension. VOLN and EXT may be omitted 
when default names are assumed, such as the system volume and a blank extension. 

A File Descriptor is also used to describe a device, in which case the VOLN field describes a device mnemonic rather than a 
volume name. The colon following the device mnemonic must be retained to avoid confusion with a file specification 
having a default volume name and extension. The FILENAME and EXT fields are ignored for devices and should not be 
used. 

File Organization 

A file is a collection of related records. From a programmer's point of view, a file is made up of logical records which may 
be of arbitrary length and structure, and are process-dependent. From the system's point of view, a file is made up of 
physical blocks which are of fixed length appropriate to the particular device and are process-independent. When a user 
program is written, the logical file structure must be considered because certain information is required at execution time 
by the I/O processor routines and therefore must be supplied by the user program. When a file is allocated, the manner in 
which the data is to be stored physically on the device must be specified. 

OS/16 MT2 supports two file structures. Although these structures differ, in many cases the same data manipulations can 
be performed on one structure as another. The choice of file structure, in most applications, does not depend on the form 
of the data to be put in the file, but on the way in which the data is accessed. OS/ 16 MT2 file structures are each 
optimized for one specific form of access. 

Indexed Files 

The Indexed file is an open ended file structure consisting of two types of physical blocks: a chain of index blocks and 
individual data blocks pointed to by the index blocks. Figure 1-3 illustrates the relationship of the two types of blocks. 

Both the index blocks and data blocks may be scattered on the volume. An Indexed file may be accessed sequentially or 
randomly. The index block stiructure reduces the number of physical accesses necessary to locate a specific data block. 

Logical records may be added sequentially to the end of the Indexed file at any time. Existing logical records may be 
overwritten either sequentially or randomly, but cannot be deleted. For random access, logical records are referenced by a 
logical record number which is a number ranging from to the number of logical records in the file minus 1. This logical 
record number indicates the order in which the logical record was added to the file. 

When an Indexed file is allocated, the logical record size of the data to be contained is specified, as well as the physical 
block size of both tlie index blocks and the data blocks. 

Access to the logical records on an Indexed file is via the Logical Buffered Access Method, which means that logical record 
length is independent of the physical block size specified for the data blocks. All blocking and deblocking is performed 
automatically by the OS via a buffer allocated in system space along with the File Control Block (FCB) when the file is 
assigned. 

Contiguous Files 

The Contiguous file is a fixed-length file structure. All blocks of a Contiguous file are allocated contiguously on the volume 
as illustrated by Figure 1-3. The file size (in 256-byte sectors) is specified at the time of allocation, and all required space is 
reserved at that time. Each sector (block) is considered a record by the system. Random reads and writes may access any 
record on the file, regardless of which records have been previously accessed. This makes it possible to create a Contiguous 
file in a random fashion. 
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Figure 1-3. OS/16 MT2 FUe Structures 
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Contiguous file I/O is non-buffered and transfers a variable amount of data directly to or from the task's buffer. Although 
the user may transfer data in logical records of size greater or smaller than a sector, the appropriate sector number must be 
specified to position the file for random access. All transfers begin on a sector boundary and end whenever the specified 
number of bytes has been transferred. 

The Contiguous file supports a pseudo filemark capability that gives it some of the characteristics of a magnetic tape 
device. A filemark is indicated by a halfword of X" 13 13' at the beginning of a record (block). Care should be taken to 
ensure that this datum is not inadvertently written at the beginning of a record if filemark operations are going to be used. 
The forward-file and backward-file operations, on a Contiguous file, function as they would on a magnetic tape. That is, 
the file is positioned forward or backward respectively until a filemark (X'1313') is found. The current record pointer is 
then left at the record following or containing this filemark, respectively. The write-fllemark operation results in writing 
X'13 13' at the beginning of the current record. 

File Access Methods 

OS/16 MT2 supports two methods of access to files: random and sequential. These methods may be intermixed without 
having to close and reassign the file. The chief mechanism used to implement these methods is the current record pointer. 

The current record pointer is a number, ranging from zero to the number of logical records currently in the file, indicating 
the record to be read or written on the next sequential access to the file. Each record is numbered in sequence, starting 
with zero. 

The current record pointer is adjusted in one of several ways: 

1. It is set to zero by the following operations: 

Rewind 

Backspace to filemark (except on Contiguous files where the record pointer is positioned at the 
record containing the filemark) 

Assigning (except for Write-only access) 

2. It is set to the number of records in the file (the proper position to append new records) by the 
following operation: 

Assigning for Write-only access 

Forward to filemark (except on Contiguous files where the record pointer is positioned after the 
record containing the filemark). 

3. It is decremented by one by a backspace record operation, unless the file is already positioned at its 
beginning. 

4. It is incremented by one as follows: 

Forward record (unless already at end of file) 

Write filemark to a Contiguous file 
Sequential Read or Write to an Indexed file 

5. A random Read or Write sets the current record pointer to a value one greater than the record read or 

written. 

6. It is incremented by the number of sectors that must be accessed to satisfy a sequential Read or Write 
request to a Contiguous file. 

Random Access 

For random access, the user supplies the record number that is to be accessed. This record is found, the data transfer is 
performed, and the current record pointer is set to point to the next sequential record. If the user continues to use random 
access, the current record pointer may be ignored, since it is readjusted on every call. However, the user may wish to read 
or write a sequence of records, starting with a known record number. In this case, a single random call followed by a 
number of sequential calls may be used. 

With an Indexed file, the user is somewhat restricted in the use of the random Write call. This call may be used to update 
any record currently in the file, or to append one record to the end of the file. If the record number specified is more than 
one record past tlie end of the file, the call is rejected. This means that a file must be expanded in a sequential manner. If 
the file has only five records, a sixth may be added but record number 100, for example, may not. 

On Contiguous files there is no restriction on the use of the random Write or Read call. Any record within the file's 
allocation may be read or written. 
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Sequential Access 

Sequential access is the simplest and most common access method. The user performs a series of sequential Read or Write 
calls. These cause records of the file to be read or written in sequence. The current record pointer is adjusted automatically 
at each access. The Rewind, Forward Record, Backward Record, Forward File and Backward File commands may be used 
for repositioning as described previously. 

File and Device Protection 

Files and devices may be protected in one of two ways: statically or dynamically. 

Static Protection 

Each file or device has associated with it two protection keys, one for Read access and one for Write access. Each key is 
one byte long and may have any value from X'OO' to X'FF". 

If the values of the keys are within the range of X'Ol' to X'FE', the file or device may not be assigned for Read or Write 
access unless the operator or requesting task supplies the matching keys. 

If a key has a value of X 00 , the file or device is unprotected for that access mode. Any key supplied is accepted as valid. 

If a key has a value of X FF , the file is unconditionally protected for that access mode. It may not be assigned for that 
access mode to any user task, regardless of the key supplied. An unconditionally protected file may be assigned to an 
Executive task, including the Command Processor. 

Some examples of static protection follow: 

Meaning 
Completely unprotected. 

Unconditionally protected. 

Unprotected for Read, conditionally protected for Write (user must supply Write key = 
X'07'). 

Unconditionally protected for Write, conditionally protected for Read. 

Conditionally protected for both Read and Write. 

The protection keys of a file are defined when the file is allocated, and may be changed by the console operator or by any 
task having that file assigned for exclusive Read/Write access. (See Dynamic Protection.) 

The protection keys of a device are set to zero at system generation time, and may be changed by the console operator or 
by an E-Task. 

Dynamic Protection 

When a task has assigned a file, it may wish to prevent other tasks from accessing that file while it is being used. For this 
reason, the user may ask for exclusive access privileges, either for Read or Write, at assignment time. This form of 
protection is called dynamic because it is only in effect while the file remains assigned. 

The access privileges are generally known by their abbreviations. These are: 

SRO Shared Read-Only 

ERO Exclusive Read-Only 

SWO Shared Write-Only 

EWO Exclusive Write-Only 

SRW Shared Read-Write 

SREW Shared Read, Exclusive Write 

ERSW Exclusive Read, Shared Write 

ERW Exclusive Read-Write 

A file cannot be assigned with a requested access privilege if that assignment is incompatible with some other existing 
assignment of that file. For example, a request to assign a file for Exclusive Write-Only is compatible with an existing 
assignment of that file for SRO or ERO, but is incompatible with any existing assignment for other access privileges. Table 
1-1 shows compatibilities and incompatibilities between access privileges. 



Write 


Read 


Key 


Key 


00 


00 


FF 


FF 


07 


00 


FF 


A7 


27 


32 
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Write Protection 

All files on a disc volume may be protected from Write operations by marking the disc on-line as a protected device. When 
a volume is marked as being Write protected, all assigns for access privileges other than Shared Read Only (SRO) and 
Shared Read/Write (SRW) are rejected with a privilege error: Shared Read/Write (SRW) is changed to Shared Read Only 
(SRO). If the hardware write protected feature of a disc is enabled, the volume must be marked on-line as a protected 
volume. 

Null Device 

If a task performs I/O requests via SVC 1 calls, but no actual transfer is desired (possibly during testing), the Logical Unit 
(LU) used in the transfer may be assigned to the Null device before starting the task. The OS/ 16 MT2 Configuration Utility 
Program configures every OS/ 16 MT2 with a Null device which may be referenced by the File Descriptor: 

NULL: 

Read requests to the Null device return EOF status with the specified buffer unchanged. All write requests return with 
normal status and a length of data transfers of zero. 



TABLE 1-1. ACCESS PRIVILEGE COMPATIBILITY 




SKEW 



HWO 



SWO 



SRW 



SRO 



ERO 



HRSW 



KRW 



SREW 

EWO 

SWO 

SRW 

SRO 

ERO 

ERSW 

ERW 



* = compatible 
- = incompatible 
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CHAPTER 2 
TASK MANAGEMENT 



TASKS 

Tasks are controlled by OS/16 MT2 through two system control blocks: the Task Control Block (TCB), and the User 
Dedicated Locations (UDL). The TCB is maintained in system space and therefore cannot be modified by a user task. The 
Use"r Dedicated Locations (UDLs) are maintained in the task's own allocation, therefore providing a measure of self-control 
to the task. This chapter describes the data structures and services related to task management. 

Most of the services described here are invoked through the Intertask Communication Supervisor Call (SVC 6) described in 
Chapter 3. • 

Interrupts and Traps 

In OS/16 MT2, as in most operating systems, all interrupts at the processor level, both external and internal, are handled 
by the operating system. OS/16 MT2 provides an interrupt facility at the task level known as the task-handled trap facility. 
This facility permits a task to be interrupted out of its normal execution sequence for any one of a variety of causes, both 
hardware and software-generated. This facility also allows one foreground task to pass a parameter to another foreground 
task via the receiving task's Task Queue, thus permitting the receiving task to determine the software defined reason for the 
interrupt. A task handled trap may occur for the following reasons: 

Power Restoration 

Addition of an item to the Task Queue 

Completion of an I/O proceed request 

External Interrupt from a Trap Generating Device 

Completion of a specified time delay 

Message received from a task 



Task Status Word (TSW) 

Traps, and additions to a task's Task Queue are controlled through the task's Task Status Word (TSW), which is the task 
level analog of the 1 6-Bit' Processor Program Status Word (PSW). This status word is used to enable or disable the various 
traps, enable or disable additions to the Task Queue, and to save the location counter and condition code of a task at the 
time of a trap. TSW bit assignments are shown in Figure 2-1. The current Task Status Word (TSW) is maintained by the 
system for each task in its Task Control Block (TCB). The initial value of a task's TSW is set by the user (or by default) at 
task establishment time. 

^\"^° 15 







STATUS 



LOC 



Figure 2-1 . Task Status Word (TSW) 

Task Status Word is 32 Bits. First halfword (bits 0-15) contains status defined in Figure 2-2. Second halfword (bits 16-31) 
"contains the current location counter as in a PSW. 
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BIT 


HEX MASK 


NAME 


DESCRIPTION 





8000 


W 


Trap Wait. Task suspended Until a task trap occurs. 




1 


4000 


P 


Power Restoration Trap Enable. A task trap occurs 
on completion of system power restore sequence. 


2-3 






Reserved. Must be Zero. 


4 


0800 


Q 


Task Queue Service Trap Enable. A task trap 
occurs when an item is added to the Task Queue. 
Also a trap occurs if a TSW is loaded with this bit 
set and the Task Queue is not empty. 


5 






Reserved. Must be Zero. 


6 


0200 


D 


Enable Task Queue entry on interrupt from a 
connected Trap Generating Device. 


7 


0100 


T 


Enable Task Queue entry on Queue Parameter 
(SVC 6) request directed at this task. 


8 


0080 


Z 


Enable Task Queue entry on completion of a time 
interval. 


9 


0040 


O 


Enable Task Queue entry on completion of I/O 
proceed request. 


10 






Reserved. Must be Zero. 


11 


0010 


E 


Enable Task Queue entry on send message 


12-15 


000 F 


CC 


Condition Code (as in PSW). 



Figure 2-2. Task Status Halfword 



User Dedicated Locations (UDL) 



A minimum of 36 bytes at tile start of a taslc's program address space must be reserved for the User Dedicated Locations. A 
68 byte UDL is required for a task which uses Single Precision Floating Point, and 132 bytes for a task which uses Double 
Precision Floating Point (with or without single precision). The UDL contains system pointers, TSW swap areas, and other 
data used for communication between the operating system and the task, plus floating point register save areas as required. 
A map of the UDL is given in Figure 2-3. A task's UDL will, by default, be reserved and initialized to zero by TET/16 
when the task is established. The UDL can then be set up dynamically by the task at run-time, if necessary. Alternatively, 
the UDL area can be assembled as part of the task, or as a sub-program to be included as the first part of the task. The 
program containing the UDL must be biased at the first address of the specified partition during task establishment. See 
Chapter 5 of the OS/16 MT2 Operator's Manual for further information. 



tTOP 



This location contains the address of the highest halfword in the task's allocated memory 
(program segment). This address does not reflect the possible use of a resident library or 
Task Common partition. 



COMBOT 



This location is provided for compatibility with previous INTERDATA operating systems. 
COMBOT is always set equal to CTOP in OS/ 16 MT2. 



UTOP 



This location contains the address of the first halfword following the user program. This 
value may be modified by the use of Get and Release Storage Supervisor Calls (SVC 2). 
UTOP always contains an address aligned on a halfword boundary. 
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UBOT 

TSW Swap areas 

A(TASKQ) 

A(MESSAGE BUFFER) 



This location contains the lowest address in the user program segment. 

These are provided for Power Restoration and Task Queue Service Traps. They are each four 
halfwords in length. The first two halfwords of each location serve to save the previous TSW 
when a trap occurs; the new TSW is taken from the second two halfwords. 

This location contains the address of the Task Queue. It must be set up by the program 
prior to enabling any entries to the Task Queue. If the contents of this location is zero, no 
Task Queue entries are made, regardless of the state of the TSW enable bits for Queue entry. 

Tliis location contains the address of a 74 byte buffer beginning on a halfword boundary. 
This field must be set up by the task prior to receiving a message. If the content of this loca- 
tion is zero, no message can be received regardless of the TSW queue entry enable bit. 



0(0) 


CTOP 


2(2) 

COMBOT 


4(4) 


UTOP 


6 (6) 

UBOT 


8(8) 


A(TASKQ) 




10(A) 


POWER RESTORE OLD TSW SAVE AREA 


14(E) 


POWER RESTORE NEW TSW 


18(12) 


TASK QUEUE SERVICE OLD TSW SAVE AREA 


22(16) 


TASK QUEUE SERVICE NEW TSW 


26(1 A) 


A(MESSAGE BUFFER) 


28(1C) 

RESERVED 


30(1E) 


RESERVED 


36 (24) 


SINGLE PRECISION 
FLOATING POINT REGISTER 
SAVE AREA 


68(44) 


DOUBLE PRECISION 

FLOATING POINT REGISTER 

SAVE AREA 



132(84) 



Figure 2-3. User Dedicated Locations (UDL) 
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TASK-HANDLED TRAPS 

When a condition occurs that causes a trap, a TSW describing the routine to handle the specific type of trap is loaded from 
the appropriate new TSW in the task's User Dedicated Locations (UDL), the task's current TSW is saved in the UDL and 
control is passed to the routine to handle the trap. It is the trap routine's responsibility to save all general or floating point 
registers used within the routine prior to servicing the trap. A Load TSW Supervisor Call (SVC 9) is used to load the saved 
current TSW, thus returning control to the normal execution sequence. 

If a task is in any Wait state other than Trap Wait, a trap does not actually occur until the task has left that Wait state. The 
TSW swap occurs upon detection of the condition causing the trap; however, the task remains in the Wait state until the 
reason for that wait is removed. Multiple TSW swaps may occur before the task leaves the Wait state, if so enabled. It is the 
responsibility of the user to assemble, or dynamically prepare, the desired new TSWs in the UDL for each type of trap, if 
the task trap facility is to be used. 

Task Queue Service Traps 

Since several trap-causing conditions may occur before the first trap is handled by the task, the Task Queue facility is 
provided to allow for queuing of trap information during periods when the task is unable to service a trap. 

Tlie following trap-causing conditions cause an item to be added to the task's Task Queue: 

Addition of a parameter to the Task Queue 
Completion of an I/O proceed request 
External Interrupt from a Trap Generating Device 
Termination of a specified time delay 
Message received from a task 

As shown in Figure 2-2, each of these reasons can be independently disabled by setting the appropriate enable bit to 
ZERO. 

The Task Queue is a "circular list" in the standard INTERDATA list-processing format. This list may be of any size 
desired, and may be located anywhere within the user program. It should be large enough to contain all parameters which 
may be queued at any one time. If the queue is full, attempts to add to the queue are rejected by SVC 6. A pointer to this 
list must be placed in the User Dedicated Locations by the program before enabling Task Queue entries. 

The system always adds items to the bottom of the Task Queue. 

Table 2-1 lists the parameters that are added to a Task Queue by the OS. If the Task Queue is full, any entries the system 
attempts to queue are lost. 



TABLE 2-1. TASK QUEUE ENTRY TYPES 



TYPE 


CONTENTS 


Device Interrupt 


Parameter associated with device in SVC 6 connect time. 


SVC 6 Queue Parameter 


Parameter specified in Add Parameter To Task Queue call (SVC 6) 


I/O Proceed Complete 


Address of I/O Call (SVC 1 ) parameter block. 


Interval Completion 


Parameter specified at interval initiation (SVC 2 Code 23) 


Task Message 


Address of message buffer 
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Power Restoration Traps 

A task may wish to be informed if the processor has executed a power fail/restore sequence. Upon power failure, OS/ 16 
MT2 saves all necessary data so that system operation can resume when power is restored. Although the system is able to 
resume normally, the same is not always true of tasks, since I/O requests may have been aborted or a time interval may 
have been missed. 

Any 1/0 operation in progress when power fails is aborted. If the operation is on a direct-access device, the system is able 
to retry it when power is restored; however, on other than direct-access devices, a retry is generally impossible. These I/O 
operations, therefore, return an unrecoverable error status to the task. 

If a task has real-time considerations, power restoration may indicate that an appreciable amount of time elapsed while 
power was down. This fact, and the lack of knowledge at the task level as to how long the power outage lasted, may pose 
substantial difficulties to a real-time task. 

The normal course of events, in case of power outage, is to pause all tasks in the system. However, a task may choose to 
take a Power Restoration trap, instead of being paused. 

If this is the case, the task should keep the P bit (Bit I) set in its current TSW. Then, whenever there is a power outage, a 
TSW swap occurs upon restoration of power, and the task can go about the business of recovering from the power outage. 

Trap-Generating Devices (TGD) 

In certain applications, it is desirable for a task to respond to interrupts from some external device. OS/ 16 MT2 provides a 
set of facilities to allow this to be done. 

Certain drivers, in particular the Eight-Line Interrupt Module driver, are capable of adding a parameter to a task's Task 
Queue in response to an interrupt from the device. The addition to the Task Queue can cause the task to take a trap, if 
enabled. For this reason, these devices are called Trap-Generating Devices (TGD) and their drivers are called TGD drivers. 

Most devices, such as TTY, Card Reader, et cetera, are not capable of being used in this way. The only driver offered with 
OS/ 16 MT2 that supports TGD functions, is the Eight- Line Interrupt Module driver. 

The functions provided by OS/16 MT2 for the handling of TGDs implement the entire ISA (Instrumental Society of 
America) proposed standards for process control. These functions are: 

Connect attaches a TGD to a task 

Thaw enables interrupts on a TGD 

SINT simulates an interrupt on a TGD (Addition to ISA standard) 

Freeze disables interrupts on a TGD 

Unconnect detaches a TGD from a task 

INTERRUPTS 

Interrupts handled by the OS/16 MT2 Executive are: Floating Point and Fixed Point Divide Arithmetic Faults, Illegal 
Instruction, Machine Malfunction, and Memory Protect Fault. 

Floating Point and Fixed Point Divide Arithmetic Faults 

When an Arithmetic Fault interrupt occurs, the task causing it may either be paused or continued, depending on selected 
task option. In either case, a message is output to the system log. The task has the further option of disabling arithmetic 
fault interrupts entirely, by the use of the Set Status Supervisor Call (SVC 2 Code 4). If an Arithmetic Fault occurs in 
system code execution, the crash handler is entered. 

Illegal Instruction 

If the illegal instruction was executed within system code, the crash handler is entered; if the illegal instruction was 
executed within user code, a message is output to the system log and the task is paused. 

The previous statement does not apply if the illegal instruction interrupt was caused by the execution of a floating-point, 
multiply/divide or list instruction on a system using software traps. In that case, the appropriate trap routine is entered and 
the execution of the instruction is emulated. 
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Machine Malfunction 

The machine malfunction interrupt occurs on memory parity error, power failure, and power restoration. 

A memory parity error causes a system crash if it occurs within system code; otherwise, a message is output to the system 
log and the active task is paused. Memory parity errors may occur when addressing non-existent memory in a processor 
with the parity feature installed. 

Power failure causes the system to prepare for an orderly shutdown and to prime itself to await the machine malfunction 
interrupt that is to occur on power restoration. 

On power restoration, a message is logged requesting the console operator to reset all I/O devices (such as disc, which may 
not be ready or may come up in a Write-disabled state). When this message is acknowledged by the operator, all pending 
I/O requests are terminated, except those on direct-access devices, which are retried. All tasks in memory are then paused, 
except for those with a TSW enabling a task-handled trap on power restoration. The SET TIME command should be used 
to reset the clock as soon as possible following power restoration. 

Memory Protect Fault 

This interrupt occurs when a task attempts to violate the conditions of memory protection imposed by the Memory 
Protect Controller (MPC). A message is output to the system log and the errant task is paused. 



TASK STATUS AND OPTIONS 

Task Status and Options halfwords are maintained by the system in the Task Control Block (TCB). Task Options, in 
general, define overall characteristics of the task while the Task Status defines the state of the task. Tables 2-2 and 2-3 
define the meanings of the Status and Options halfwords. 

TABLE 2-2. TASK OPTIONS 



BIT 


HEX MASK 


SYMBOLIC 


MEANING 





8000 


ET 
UT 


Executive Task (E-task) if 1 
User Task (U-task) if 


1 


4000 


AFC 
AFP 


Arithmetic Fault Continue if 1 
Arithmetic Fault Pause if 


2 


2000 


FLOAT 
NOFLOAT 


Task uses Single Precision Floating Point registers if 1 
Task does not use Single Precision Floating Point 
registers if 


3 


1000 


RES 
NONRES 


Task is Memory Resident if 1 
Task is non-resident if 


4 


0800 


COMP 
NOCOMP 


Task uses BOSS/DOS/RTOS SVC 1 and SVC S format if 1 
Task uses OS/16 MT2 SVC 1 and SVC 5 format if 


5 


0400 




Task is background task if 1 . 
Task is a foreground task if 


6 


0200 




SVC 6 ignored (Background only) if 1 
SVC 6 illegal (Background only) if 


7 


0100 


ROLL 
NOROLL 


Task is rollable if 1 
Task is not rollable if 


8 






Reserved for system use 


9 


0040 


D FLOAT 
NODFLOAT 


Task uses Double Precision Floating Point registers if 1 
Task does not use Double Precision Floating Point 
registers if 


10 


0020 


CSEG 
NOCSEG 


Program Addresses 0-7FFF are mapped to physical memory 
8000-FFFF if 1 or physical memory 0-7FFF if 
(extended memory systems only) 


11-15 






Reserved for system use 
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TABLE 2-3. TASK STATUS 



BIT 


HEX MASK 


MEANING IF SET 





8000 


Dormant 


1 


4000 


I/O Wait 


2 




Reserved 


3 


1000 


Roll Wait 


4 




Reserved 


5 


0400 


Console Wait (Paused) 


6 


0200 


Time Wait 


7 


0100 


Trap Wait 


8 


0080 


SVC 2 Wait 


9 


0040 


SVC 5/6 Wait 


10 


0020 


SVC 7 Wait 


11 


0010 


Reserved 


12 


0008 


DCB Wait (File I/O Wait) 


13-15 




Reserved 
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CHAPTER 3 
SUPERVISOR CALLS 



SVC INSTRUCTIONS 

The SVC instmction enables a user task to communicate with the operating system and to use the software facilities 
provided. Execution of an SVC instruction at the assembly language level causes an internal interrupt which is processed by 
the Executive of OS/ 16 MT2. Higher level languages provide statements which generate SVC instructions. 

The general form of an SVC instruction is: 

SVC n,P 



Where: 



specifies the particular SVC 

represents a parameter or the address of a parameter block which further defines the request. 

Parameter blocks must be aligned on a halfword boundary. 



Valid SVC Calls 



OS/ 16 MT2 provides all SVC instructions supported by OS/32 MT except for the OS/32 AIDS Support Supervisor Call 
(SVC 14), although not every option of each OS/32 MT SVC is supported. Table 3-1 summarizes the SVCs supported by 
OS/16MT2. 



TABLE 3-1. OS/16 MT2 SUPERVISOR CALLS 



SVC 


CODE* 


FUNCTION 


1 




I/O Request 


2 


1 


Pause 




2 


Get Storage 




,3 


Release Storage 




4 


Set Status 




5 


Fetch Pointer 




6 


Unpack 




7 


.|, Log Message 




8 


V Interrogate Clock 




9 


5 Fetch Date 




15 ; 


1 Pack Numeric Data 




16 \ 


Pack File Descriptor 




17 


Mnemonic Table Scan 




18 


Move ASCII Characters 




19 


Peek 




23 


Timer Management 


3 




End of Task 


5 




Fetch Overlay 


6 




Intertask Coordination 


7 




File Management Services 


9 




Load TSW 



"The code number appears in the SVC 2 parameter block. 
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SVC Errors 

OS/ 16 MT2 processes errors in an SVC instruction by issuing a message to the system console and pausing the task. 
The two possible error condition, and their causes are: 

1. Illegal SVC which indicates an illegal SVC number (n), or invalid parameter specified in the parameter 
block. 

2. Invalid Address in SVC which indicates an invalid parameter block address (not in task's allocation, 
or not on a halfword boundary), or an invalid address specified in a parameter block. 

In either case the address of the errant SVC instruction is displayed in the message. 

SVC 1 - INPUT/OUTPUT REQUESTS 

SVC 1 is used by a task to perform all I/O requests. The parameter block format required to define the request is: 



0(0) 


FUNCTION CODE 


1(1) 

LOGICAL UNIT 


2(2) 


DEVICE INDEPENDENT STATUS 


3(3) 

DEVICE DEPENDENT STATUS 


4(4) 


BUFFER START ADDRESS 




6(6) 


BUFFER END ADDRESS 




8(8) 


RANDOM ADDRESS 
(4 BYTES) 


- 


12(C) 


LENGTH OF DATA TRANSFER 




14(E) 


COMIVIUNICATIONS 

EXTENDED OPTIONS 

(ITAM/ieONLY) 


- 



18 (12) 

This parameter block must be on a halfword boundary and must be in a writable segment of the program address space. An 
SVC 1 call may be coded as follows: 





SVC 


1, PARBLK 






ALIGN 


2 






DB 


X'function code' 


FUNCTION CODE 


PARBLK 


DB 


X'logical unit' 


LOGICAL UNIT 




DS 


2 


STATUS 




DC 


A(START) 


START ADDRESS 




DC 


A(END) 


END ADDRESS 




DC 


Y'RANDOM' 


RANDOM ADDRESS 




DS 


2 


LENGTH OF DATA TRANSFER 




DC 


Y'COMOPT' 


COMMUNICATIONS OPTIONS 
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Data Transfer Requests 

The function code field for a data transfer request is defined in Table 3-2. 



TABLE 3-2. SVC 1 DATA TRANSFER FUNCTION CODE 



BIT 




1-2 



ALIGNMENT 



X. .. 
.XX. 



X... 



.X. 



MEANING 



This bit must be ZERO to indicate a data transfer request. 

Read-Write bits. The meaning of these two bits is modified by bits 3-7 to control the transfer. 
Basically the values are: 

10 - Road request 
01 ■ Write request 

1 1 - Test and Set request (see Chapter 8 on Contiguous Files) 

00 - Wait only or Test I/O Complete 

ASCII/BINARY bit. This bit indicates the type of formatting requested if Bit 7 Is reset. 
0- indicates ASCII formatting 

1 - indicates binary formatting 

If Bit 7 is set, this bit must be ZERO. 

PROCEED/WAIT bit. This bit indicates the action to be taken after the I/O has been initiated. 

- Proceed. Indicates that control is to be returned to the task after initiation of I/O. 

1 - Wait. Indicates that the task is to be put into I/O Wait until the data transfer is 

complete. 

SEOUENTIAL/RANDOiVI bit. 

- Sequential. Indicates the next logical record is to be accessed. 

1 - Random. Indicates the logical record specified by the RANDOIVI field is to be 

accessed. 

UNCONDITIONAL PROCEED bit. 

- indicates the task is to be put into I/O wait until the requested device/file is free. At 

that time the request is processed. 

1 - indicates that the request is to be rejected with a condition code of X F if the 

requested device/file is not free. 

FORMATTED/IMAGE bit. 

- indicates that the request is to be formatted according to the device/file and the 

setting of Bit 3. For communications devices indicates default extended options to be 
used. 

1 - indicates that no formatting is to be performed (Image mode). For communications 

devices indicates Extended Option field applies. 



In general, the request is defined by the logical OR of the function code bits. The ZERO setting of each bit is valid for all 
devices/files. If any invalid ONE setting of a bit is specified, the request is rejected by the OS as an illegal function (see 
STATUS byte definition). 

For example, a function code of X'5C' specifies a request for: 

Read(X'40') 

Binary Formatting (X'lO') 
Wait I/O (X'08') 
Random Access (X'04') 

The full SVC 1 parameter block, except the communications extended options field, must be reserved for data transfer 
requests. Wait only and Test I/O complete requests make use of the function code, logical unit, and status fields only, so 
the remaining fields may be redefined and used by the task (e.g., for storing constants, etc.). 
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Command Function Requests 

The function code for a command function request is defined in Table 3-3. 

TABLE 3-3. SVC 1 COMMAND FUNCTION CODE 



BIT 


ALIGNMENT 


MEANING 





X 


This bit must be set to indicate a command function request. 
This bit alone requests Halt I/O 


1 


.X 


Rewind 


2 


. .X 


Backspace Record 


3 


. . .X .... 


Forward Space Record 


4 


. . . .X. . . 


Write File Mark (EOT for communications device.) 


5 


X. . 


Forward Space File 


6 


X. 


Backspace File 


7 


X 


Reserved for driver dependent functions 



The implementation of all commands is device-dependent and is explained for each driver in Chapter 8. The implemen- 
tation of command functions for direct-access files is also explained in Chapter 8. 

When multiple bits in the command function code byte are set, the following principle applies: 

The function code is scanned from left to right. The leftmost bit found that is meaningful to the device 
assigned to the specified logical unit indicates the function to be performed. 

If no valid function is indicated by the function code, the system returns immediately to the user, with normal status. Note 
that this condition is not considered an error. The user may find out which command functions are supported on any 
Logical Unit by means of the Fetch Attributes (SVC 7) call. 

Most drivers do not make use of the fields following the Device Dependent Status field (for commands). If the user is 
certain that no special drivers are to be used by the task, these fields may be put to other uses, e.g., the storing of con- 
stants, etc. However, for a fully device-independent program, it would not be appropriate to use these fields. 

Logical Unit (LU) 

In order to provide device independent I/O, all I/O requests are directed to a Logical Unit (LU). An LU is a number from 
to a SYSGENed maximum (up to 63) which describes an entry in the task's LU table. The particular device or file desu-ed 
must be assigned to the specified LU via operator command (see 0SI16 MT2 Operator's Manual), or SVC 7 call prior to 
executing the SVC 1 call. If an invalid or unassigned LU is specified, the call is rejected. If no operation is desired, the 
specified LU should be assigned to the Null device. 

Error Status (Device Dependent and Device Independent Status) 

The system returns the status of the requested function in the Device Independent Status byte. This Status byte is set to 
indicate the general type of error that occurred. If there was no error, it is set to zero. In addition, the processor's 
Condition Code is set to zero. In the case of a rejected Unconditional Proceed call, the Condition Code is set to X'F'. 
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The Device Dependent byte is set to zero along with the Device Independent Status byte, if there is no error. In case of 
error, a code further explaining the error status is returned in the Device Dependent Status byte. 

The system does not modify the contents of the STATUS bytes until the requested function is complete or an error has 
been detected. While the function is in progress, the previous contents of these bytes are left unchanged. 

Specific interpretations of the error codes as they apply to devices and files are explained in Chapter 8. The general 
definition of the status bits is given in Table 3-4. 



TABLE 3-4. SVC 1 DEVICE INDEPENDENT STATUS BYTE 



BIT 



MEANING IF SET TO ONE 



Always 1 for error status 
Illegal Function 
Device Unavailable 
End of Medium 
End of File 
Unrecoverable Error 
Recoverable Error 
Illegal or Unassigned LU 



BINARY 


HEXADECIMAL 


1100 0000 


x'co' 


1010 0000 


X'AO' 


1001 0000 


X'90' 


1000 1000 


X'88' 


1000 0100 


X'84' 


1000 0010 


x'a2' 


1000 0001 


X'8l' 



Tlie SVC 1 Device Dependent Status byte is defined as follows: 



X'82' 

x'sr 

X'dn' 
X'OO' 



I/O terminated by time-out 

I/O terminated by Halt I/O 

No device dependent status (dn= device number) 

No error if device independent status is zero 



In general, for a data request, if Illegal Function, Device Unavailable, or Illegal LU status is indicated, then no data was 
transferred. Otherwise, some data may have been transferred. Device Unavailable may indicate that the device is physically 
inoperative. If the device becomes unavailable after a transfer is started, Unrecoverable Error is set to indicate the 
possibility that data was transferred. 

The Illegal Function bit is set whenever the system cannot accept the SVC 1 Function Code byte as specified, for a data 
transfer. This may be for one of the following reasons: 

1. A modifier was specified that is not supported by the device; e.g.. Binary on a CRT. 

2. A function was specified that is not supported by the device; e.g.. Read on a Line Printer. 

3. A function was specified that is not supported by the access privileges granted at Assign time; e.g., 
Read on a file that is assigned for Write-Only access. 

Buffer Address 

For data transfer requests, the buffer must be specified by the buffer start and buffer end address fields. The buffer start 
address is the firet byte in the buffer and the buffer end is the last byte in the buffer (not the first byte after the buffer). 

All buffers must be on a halfword boundary and must be fully contained in the same logical segment. Buffers used in Read 
requests must be in a writable segment. 

An Invalid Address in SVC error occurs if: 

Buffer is not on halfword boundary 

Buffer start and end are not in same logical segment 

Buffer end address is less then buffer start address 

Buffer for Read request is in Write-protected logical segment 
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Random Address 

The Random Address field is 4 bytes long and is used to specify the logical record number (starting at 0) to be accessed on 
data transfer requests if function code Bit 5 is set. The interpretation of this field is device or file dependent and is defined 
in Chapter 8. 

Length of Data Transfer 

This field is used to return the actual number of bytes transferred during a data transfer request. This field is most useful 
when dealing with variable length record devices, such as magnetic tape. This field is undefined if an error status is 
returned. (See note in the section entitled Test I/O Complete.) 

Unconditional Proceed 

Unconditional proceed I/O is used when a task does not wish to wait for the requested device or file to be free. 1/0 
requests are coordinated by the system so that only one I/O request may access any device at a time. If Unconditional 
Proceed is not requested, and the specified device is in use at the time of the data transfer request, the calling task is placed 
in I/O Wait until the device is free. At that time, the I/O request is initiated. If Unconditional Proceed is specified and the 
specified device is in use, the SVC 1 request is rejected. Error status is set to zero (normal), and the condition code is set to 
X'F'. The calling task may then retry the request at a later time. If the specified device is not in used, the setting of the 
Unconditional Proceed Bit has no effect on the request. 

Wait/Proceed I/O 

Once an I/O request has been initiated (that is, the specified device is free), an I/O Proceed call (Bit 4 of function code 
reset) causes control to be returned to the task so that the task may execute concurrently with the transfer. The status is 
not set until completion of the I/O (except for Illegal function and Illegal LU which are detected before transfer 
initiation). 

The status of the request may be checked by; 

Monitoring the status field in the parameter block 

Taking a task handled trap on completion 

Issuing a Wait Only request to the same LU to wait for completion 

Using Test I/O complete on the same LU to monitor the completion 

An I/O and Wait call (Bit 4 of the function code set) cause the calling task to be placed in I/O wait until complefion of the 
request. 

Wait Only 

A Wait Only request (function code X'08') causes the task to be placed into I/O wait until the completion of a previous 
I/O Proceed request to the specified LU. If there is no uncompleted I/O by this task to the specified LU, control is 
returned immediately. This call makes use of the FC, LU, and STATUS fields of the SVC 1 parameter block. Illegal LU is 
the only error status returned by this call. The status of the I/O being completed is returned in the parameter block 
associated with the original I/O Proceed call and not in the Wait Only call parameter block. 

Test I/O Complete 

A Test I/O complete call (function code X'02') returns with a condition code of X'O if there is no uncompleted I/O 
Proceed call to the specified LU by the task. If there is an uncompleted I/O Proceed, the call returns a condition code of 
X'F'. Illegal LU is the only error status returned by this call. The status of the I/O being tested is returned in the parameter 
block associated with the original I/O Proceed call. 



NOTE 

For compatibility with older 1 6-bit Operating Systems, a task may 
use the compatibility option and use BOSS/DOS/RTOS SVC I 
parameter block format. Under this option, the length of data 
transfer field is unused, and the random address field is one 
halfword in length. For a wait-only call, the FC, LU and STATUS 
fields are used. 
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Halt I/O Command 

Halt I/O allows a task to cancel an outstanding I/O and proceed request issued by that task. This is particularly useful on 
an interactive terminal device; without the ability to Halt I/O, an outstanding read request must be satisfied before any 
other I/O can be started on that device. 

The Halt I/O command is supported on all interactive terminal devices currently supported on the system; TTY Key- 
board/printer, Carousel, CRT devices on a Current Loop or PASLA interface. 

When a Halt I/O command is received, the system first verifies that it is a valid request: 

1 . The logical unit (LD) must be assigned 

2. The device must support Halt I/O 

3. The LU must currently have a proceed I/O request outstanding. 

If it is found to be invalid, an error status is returned to the Halt I/O request parameter block. If the request is valid, the 
I/O operation is scheduled for termination and a status of zero is returned to the Halt I/O parameter block. The driver 
aborts the I/O and sets the status of the original I/O request to X'SlSl'. 

The Halt I/O parameter block should not be the same one originally set up to request the 1/0; as a result of the Halt I/O 
request, status will be returned to both parameter blocks. After the SVC 1 is issued, the Halt I/O status should first be 
checked to ensure that the system considers the request valid. The possible values are: 

X'OOOO' The requested 1/0 termination has been scheduled 

X'8 1 00' The LU was not assigned 

X'82dn' No I/O on-going for this LU 

X'COdn' Device does not support Halt I/O 

where 

X'Sr = unassigned LU 

X'82' = recoverable error 

X'CO' = illegal function 

dn = device number 

The task will take a trap when the I/O completes if Proceed I/O traps and Task Queue Entries are enabled; exactly as for 
any other Proceed I/O completion. The parameter added to the queue is the address of the original data transfer parameter 
block, if traps are not enabled, the task can wait for completion of the Halt I/O with an SVC 1 wait only request. 

On completion due to Halt I/O request, the status returned is: 

X'828r 

where 

X'82' = recoverable error 

X'81 ' = device dependent status indicating Halt I/O request 

Note that support for the Halt I/O function is a SYSGEN option. On any system configured without this support, no 
device will support Halt I/O, and an error status of X'CO' indicating illegal function will be returned on any Halt I/O 
request. 



SVC 2 - GENERAL SERVICE FUNCTIONS 

This SVC provides a number of general service functions. These functions relate to the task's communication with the 
console operator, to memory allocation, to text-processing and command-processing functions, and to timer management. 
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All SVC 2 calls require a parameter block. The general structure of an SVC 2 parameter block is as follows: 



0(0) 1(1) 

OPTIONS CODE 



2(2) 



(other data as required) 



The CODE byte is a decimal number which may range from to 255. Not all of the 256 possible codes are implemented at 
this time; unrecognized codes are rejected as illegal SVCs. The SVC 2 codes implemented in OS/ 16 MT2 are shown in Table 
3-1. 

The OPTIONS byte is generally used to further modify the conditions of the call. Options may be used by individual SVC 
2 codes as required; these are described in subsequent sections. For those functions for which no options are defined, the 
options byte is ignored. 

The remainder of the parameter block may be as long or as short as required for proper operation of the SVC 2 code. All 
SVC 2 parameter blocks must be aligned on a halfword boundary. 

Code 1 ~ Pause 

This call is used to place a task in a Console Wait state. A PAUSE message is issued to the system log. If the operator enters 
a CONTINUE command at the system console device, the program is restarted at the instruction immediately following the 
supervisor call. The parameter block format is as follows: 



PARBLK 


ALIGN 
DB 


2 

0,1 NO OPTIONS 



Incomplete I/O Proceed requests continue to completion normally even while the task is in the PAUSEd state. 
Code 2 — Get Storage 

This call is used to provide temporary storage locations for certain subroutines called by a program, in particular 
FORTRAN Run-Time Library subroutines. This call does not increase the size of the program's memory allocation, but 
obtams locations from the program's current allocation. The parameter block format is as follows: 





ALIGN 


2 




PARBLK 


DB 


OPTION,2 


DESIRED OPTION 




DC 


h'reg' 


ADDRESS OF REGISTER 




DC 


h'size' 


NUMBER OF BYTES 



Options allowed are: 



X'OO' 



X'80' 



Get specified number of bytes 
Get all allocated storage 



If option X 00 IS specified, the system adjusts the task parameter, UTOP, upwards by the number of bytes requested The 
starting address of the storage obtained is returned in the designated register. Subsequent calls with this option obtain new 
areas. Since UTOP is maintained on a halfword boundary, requests are rounded up to the nearest halfword boundary. 

If option X'80' is specified, the system sets UTOP equal to the task parameter CTOP, thus making available all of the 
task s current allocation. The starting address of the storage obtained is returned in the designated register and the number 
of bytes obtained is placed into the parameter block's SIZE parameter. The parameter block must be in a writable logical 
segment if this option is selected. ^ 

If the call is successful, the Condition Code is set to zero. If more storage is requested than is currently available or a 
negative size is specified, an address of zero is returned, UTOP is not changed and the 'V bit of the Condition Code is set 
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Code 3 - Release Storage 

This call is the inverse of the Get Storage call (Code 2). It is used to release storage previously obtained. The format of the 
parameter block is as follows: 





ALIGN 


2 




PARBLK 


DB 


0,3 


NO OPTIONS 




DC 


ii'size' 


NUMBER OF BYTES TO BE RELEASED 



This call does not reduce the program's memory allocation. The pointer UTOP is adjusted downwards by this call, but not 
below UBOT. Since UTOP always points to a halfword boundary, it is rounded up to the nearest halfword if the number ot 
bytes released is not a multiple of 2. If the call would adjust UTOP below UBOT, or if a negative size is specified, UTOP is 
not changed and the Condition Code 'V bit is set (CC=4), otherwise the Condition Code is set to zero. 

Code 4 - Set Status 

This call allows the user to modify the Floating Point Arithmetic Fault and Fixed Point Divide Interrupt Enable bits (AF) 
and the Condition Code (CC) of the PSW. Two options are provided: the first option specifies that all allowable bits be 
modified; the second option specifics that only the Condition Code be modified. The format of the parameter block is: 





ALIGN 


2 




PARBLK 


DB 


OPTION,4 


DESIRED OPTION 




DB 


AF,CC 


NEW STATUS, CONDITION CODE 



The options allowed are: 

X'OO' Modify Status and Condition Code 
X'SO' Modify Condition Code only 

The AF byte parameter indicates how arithmetic faults are to be handled and the valid combinations are: 

X'OO' Disable Arithmetic Faults 

X'lO' Enable Fixed Point Divide Faults 

X'04' Enable Floating Point Arithmetic Fault 

X'l4' Enable both Fixed Point Divide and Floating Point Arithmetic Faults 

The CC byte parameter has the form: 

x'Ox' where x is to replace the Condition Code. 

Code 5 - Fetch Pointer 

This SVC is used by a task that wishes to determine the extents of its memory allocation or to modify its UDL. It returns a 
pointer to the base of the task's User Dedicated Locations (UDL). 

The format of the parameter block is as follows: 





ALIGN 


2 




PARBLK 


DB 


0,5 


NO OPTIONS 




DC 


h'reg' 


REGISTER SPECIFICATION 



No options are recognized. The REG field contains the number of one of the user's general registers; the pointer to the 
base of the user's UDL is returned in this register. 
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Code 6 — Unpack Binary Number 

This call is used to translate a binary number contained in a user General Register or pair of General Registers, into ASCII 
decimal or hexadecimal format. The format of the parameter block is as follows: 





ALIGN 


2 




PARBLK 


DB 


OPTION,6 


DESIRED OPTION 




DC 


A(DEST) 


POINTER TO DESTINATION 



The OPT field contains the supervisor call options. The ADDRESS OF DESTINATION field contains a pointer to a buffer 
in memory where the converted number is to be stored. This buffer may begin on any byte boundary; it must be in a 
writable logical segment. 

Options recognized are as follows: 

X'OO'+N Convert to hexadecimal 

X'20'+N Convert to hexadecimal, extended precision 

X 40 +N Convert to hexadecimal, suppress leading zeros 

X'60'+N Convert to hexadecimal, extended precision, suppress leading zeroes 

X'80'+N Convert to decimal 

X'CO +N Convert to decimal, suppress leading zeros 

N represents the length of the buffer, in bytes. If N is zero, a four-byte buffer is assumed. N must be less than or equal to 
31 (X'lF'), Note that 5 is sufficient for decimal, 4 for hexadecimal and 8 for hexadecimal extended. 

The converted number is right-justified in the buffer so that the least significant digit occupies the rightmost byte (liighest 
address) in the buffer. If the number to be converted exceeds the buffer length, most significant bytes are lost. If 
suppression of leading zeros is requested, the number is stored in the buffer right-justified, and the remaining characters, if 
any, are filled with blanks. 

The number to be converted must be supplied by the user in General Register Zero, and is assumed to be an unsigned 
16-bit binary number. In the case of the hexadecimal extended precision opfion, a 32-bit value is assumed to be in General 
Registers Zero and One. 

Code 7 — Log Message 

This call provides access from the user task to the system console (or system log device). It gives the user a means of 
outputting a message with the assurance that it is printed on the console or log device regardless of Logical Unit 
assignments in force at the time of the call. A number of options are provided and the parameter block may take one of 
two forms. Direct and Indirect Text: 

Direct Text 



PARBLK 



ALIGN 
DB 
DC 
DC 



OPTION,? 

h'length' 

c'text' 



DESIRED OPTION 

LENGTH OF MESSAGE IN BYTES 

TEXT OF MESSAGE 



Indirect Text 





ALIGN 


2 


PARBLK 


DB 


OPTION,? 




DC 


h'length' 




DC 


A(TEXT) 



Options recognized are: 



x'oo' 

X'40* 
X'80' 

x'co' 



Direct text, Formatted message 
Indirect text. Formatted message 
Direct text, Image message 
Indirect text, Image message 



DESIRED OPTION 

length OF MESSAGE IN BYTES 

ADDRESS OF MESSAGE TEXT 
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The LENGTH field specifies the length of the message in bytes. This message may be of any length and may begin on a 
byte boundary (for the Indirect text option). 

The Formatted/Image option is similar to the ASCII formatted/Image option in SVC 1. Its effect on the system console or 
log device cannot be properly predicted by the caller, however, since there exists no mechanism for fetchmg the attributes 
of the system console or log device. The Command Processor, therefore, may restrict the Image option by executing it as 
thought it were Formatted for certain devices. The primary effect of the Image option on a TTY, Carousel, or CRT is to 
suppress the automatic carriage return at end of line, or to allow multiple line messages to be logged with one SVC call. 

A Log Message call is treated as an I/O Proceed call. Message text is buffered within the system, enabling the user to 
modify or destroy the text or parameter block immediately following the call. If no entries are available on the log message 
queue, the message is lost. A message noting the lost message or messages is displayed in the system console. 

Code 8 - Fetch Time 

Tliis call is used by a task to request the current time of day from the system. The system maintains a 24-hour clock 
calibrated in seconds since midnight. A value of zero indicates midnight; a value of 86399 (X 1517F ) indicates 23:59.59. 
The clock may be interrogated in ASCII or binary format. The format of the parameter block is: 





ALIGN 


2 




PARBLK 


DB 


OPTION,8 


DESIRED OPTION 




DC 


A(BUFFER) 


ADDRESS OF BUFFER 



Options recognized are: 

x'oo' 

X'80' 



ASCII format 
Binary format 



If ASCII is selected, the receiving buffer must be eight bytes long and may be aligned on a byte boundary. The stored 
data is in the format: 

hh:mm:ss 

If Binary is selected, the receiving buffer must be four bytes long and aligned on a halfword boundary. The data stored in it 
is a binary fuUword indicating seconds since midnight, as described previously. 

This SVC call is ignored in a system which does not have CLOCK support. 

Code 9 - Fetch Date 

This call is used to request the present date from the system. The format of the parameter block is: 





ALIGN 


2 




PARBLK 


DB 


0,9 


NO OPTIONS 




DC 


A(DEST) 


ADDRESS OF RECEIVING BUFFER 



The receiving buffer must be eight bytes long and aligned on a halfword boundary, in a writable logical segment. The 
system returns the date in the following format: 

mm/dd/yy 

Alternatively, at system generation time, the following format may be selected: 

dd/mm/yy 

This format is widely used outside the United States and in certain governmental (chiefly military) applications within the 
United States. 

This SVC call is ignored in a system which does not have CLOCK support. 



29-429 R05 12/78 



3-11 



Code 15 — Pack Numeric Data 

This call is the inverse of the SVC 2 code 6 call. It translates ASCII hexadecimal or decimal character strings to binary 
numbers. An option is provided to skip leading blanks. The format of the parameter block is as follows: 



PARBLK 



ALIGN 

DB 

DC 



OPTIONS, 15 
H'REG" 



DESIRED OPTIONS 

REGISTER HOLDING ADDRESS 



Options recognized are: 

X 00 Hexadecimal 

X'20' Hexadecimal, extended precision 

X40' Hexadecimal, skip leading blanks 

X'60' Hexadecimal, extended precision, skip leading blanks 

X'80' Decimal 

X'CO Decimal, skip leading blanks 

The REGISTER field of the parameter block specifies one of the user general registers. This register must contain a pointer 
to the first character of the ASCII string to be converted. The result is returned in General Register Zero. If extended 
precision is specified for hexadecimal, the result is a 32-bit value returned in Registers Zero and One. 

This pointer register is returned pointing to the first byte in the string that could not be converted. (If decimal is specified, 
this is the first non-numeric byte; if hexadecimal is specified, this is the first byte that is not 0-9 or A-F.) If Register Zero 
(or One) is specified as REG, the updated input pointer is not returned. 

Tlie Condition Code (CC) is set to reflect the results of the processing: 

CC=0 means a normal termination with no errors encountered in packing. 

CC=1 ('L' bit set) means no characters were processed; in this case, the result is set to zero. 

CC=4 ('V bit set) means that the number processed was too large to be represented. If hexadecimal is 
specified, this means that more than four valid hexadecimal digits were processed (eight, if extended pre- 
cision); in this case, the result contains the least significant four or eight characters. 

If decimal is specified, this means that the number processed is greater than l^^-l (65535). In this case, 
Register Zero contains the number processed, modulo 2^^. 

Code 16 - Pack File Descriptor 

This call is used to convert an ASCII string containing a File Descriptor into tiie format necessary for a File Management 
^ervices Call (SVC 7). This call is particularly useful if the name of the system volume is not known to the caller The 
format of the parameter block is: 



PARBLK 



ALIGN 
DB 
DC 
DC 



OPTIONS, 16 

H'REG' 

A(DEST) 



DESIRED OPTIONS 

ASCII STRING ADDRESS REGISTER 

ADDRESS OF RECEIVING AREA 



The REG field specifies one of the caller's general registers. This register must point to the ASCII string to be processed. 

The RECEIVING AREA ADDRESS field points to a 16-byte receiving area. This receiving area must be aligned on a 
halfword boundary in a writable logical segment and is formatted as follows: 



(0) 


VOLUME NAME 




4 (4) 


FILE NAME 




12(C) 


EXTENSION 


15(F) 
(reserved) 



Note that this is the same format as the File Descriptor field of an SVC 7 parameter block. The receiving area may in fact 
be such a field. 
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Options recognized are: 

X'OO' 
X'40' 
X'80' 
X'CO' 



Default System Volume 

Default System Volume, Skip Leading Blanks 

No Default Volume 

No Default Volume, Skip Leading Blanks 



If either "Skip Leading Blanks" option is selected, the SVC ignores all blanks from the current position of the pomter to 
the first non-blank. Otherwise, the File Descriptor to be converted is assumed to start at the current pointer position. The 
action of the "Default System Volume" options are shown later. 

The pointer contained in Register REG is returned after the call pointing to the first byte that is not part of the File 
Descriptor. The Condition Code is set on return as follows; 

normal 

1 no volume name present in input 

4 syntax error (input pointer not updated) 

8 no extension present in input 

9 no extension or volume name present in input 

If a syntax error is detected, the contents of the receiving area are undefined. If volume name, file name or extension is 
fewer than 4, 8 or 3 characters long, respectively, the field is left justified and unused characters in the receiving area are 
blank-filled. The reserved character following the extension field is always set to a blank by the system. 

If no volume name is provided and a "Default System Volume" option is selected, the current system volume name is 
moved into the VOLUME NAME field of the receiving area. If this option is not selected, the contents of the receiving area 
VOLUME NAME field are left unchanged. 

For example: 



1. 


Input string 


Receiving area 


Condition Code 


DSC3: 


DSCSbbbbbbbbbbbb 


8 (no extension) 


2. 


ABC:FILEl.Xy 


ABCbFILElbbbXYbb 


(normal) 


3. 


DEF:FILE2 


DEFbFILE2bbbbbbb 


8 (no extension) 


4. 


FILE4.PDQ 


****FILE4bbbPDQb 


1 (no volume) 


5. 


FILES 


****FlLE5bbbbbbb 


9 (no volume or extension) 


6. 


FRED: FILES. 


FREDFILESbbbbbbb 


(normal) 


7. 


$3%X,CP% 


undefined 


4 (syntax error) 



**** = volume name field contents depend on selected option 

Note that the selection of the blank extension (example 6) is not considered the same as the selection of no extension at 
all. If no extension at all is selected, it is assumed that the caller may wish to use some default value. A file descriptor is ■ 
terminated by any non-alphanumeric character other than a colon or a period. 



Code 1 7 - Mnemonic Table Scan 

This call permits the user to decode command mnemonics in a way identical to the OS/16 MT2 Command Processor. The 
format of the parameter block is as follows: 





ALIGN 


2 




PARBLK 


DB 


0,17 


NO OPTIONS 




DB 


REG1,REG2 


INPUT, INDEX REGISTERS 




DC 


A(MNEMONIC TABLE) 





The options byte must contain zero, as there are no options. The REGI byte contains the number of a general register. 
This register is a pointer to the source string being scanned. The REG2 byte contains the number of a general register into 
which the result of the call is put. The MNEMONIC TABLE ADDRESS field contains the address of a mnemonic table 
within the user's program space. 
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The format of a mnemonic table is a string of mnemonics. No boundary alignments are required. Mnemonics within the 
table are separated from each other by bytes containing X'OO'. The end of the table is signified by the occurrence of two 
consecutive bytes of X'OO'. 



MNEM100MNEM2 00MNEM3 00 00 



The first byte of a mnemonic may be any ASCII character; subsequent bytes of the mnemonic must be alphabetic. A 
mnemonic may be of any length. Abbreviations are permitted in the same way as described in the operator command 
syntax (see OS/ 16 MT2 Operator's Manual). To indicate an abbreviation, required characters of a mnemonic are flagged 
with Bit = 1 ; non-required characters are flagged with Bit = 0. Required characters must be contiguous and must begin 
with the first character of a mnemonic. Thus, the mnemonic RECO NFIGURE is coded as: 

DB C'R'+X'80',C'E'+X'80', C'C'+X'80',C'ONFIGURE ',0 
where the first three characters are flagged as required. Note the byte of zero at the end; this is the mnemonic terminator. 

The result, returned in Register REG2, is a number which is -1 if no match was found, or to n-1, where n is the number 
of mnemonics in the table, if a match was found. This number represents the position of the matched mnemonic in the 
table, starting with zero. Thus, if a match is found on the third item in the table, the result returned in REG2 is 2. 

REGl is returned pointing to the firet character that was not matched. This is normally a separator following the 
mnemonic in the string being scanned. If no match is found, Register REGl is returned unchanged. 



If a match is found, the Condition Code is set to zero; if no match is found, the Condition Code 'V bit is set (CC=4). 

Code 18 - Move ASCII Characters 

This call is used to move characters from an input string to a target string. The number of characters moved may optionally 
be controlled by the presence of one or more terminating characters in the input string. The format of the parameter block 
is as follows: 



PARBLK 



ALIGN 
DB 
DB 
DC 



OPTION, 18 

REG1,REG2 

A(ENSTRING) 



OPTION 

INPUT, OUTPUT POINTERS 

ADDRESS OF ENDING CHARACTER STRING 



REGl specifies the register pointing to the input string and REG2 specifies the register pointing to the output string, which 
must be in a writable logical segment. 



Options recognized are: 



X'OO' + N 



No ending characters 

Use ending character string 



where N is the number of characters to be moved. N must be less than or equal to 127 (X'7F'). 

If option X'OO' is selected, N characters are moved. The input and output string pointers are modified to point to the 
location following the last byte moved in the input and output areas, respectively. The Condition Code is set to zero. 

If option X'80'is selected, each character moved is checked against the ending character string. If this character matches 
any of the ending characters, this character is not moved and the SVC terminates, modifying the pointers as described 
previously, and setting the Processor Condition Code to zero. If the Nth character is moved and no match has been found, 
the SVC terminates as described previously, but the 'V bit of the Condition Code is set (CC=4) to signify that no ending 
character was found. 

The ending character string is formatted as follows: 



M 


Ending characters 



where M is a byte containing the number of ending characters in the string. The length of the entire string, therefore, is 
M+1 bytes. A string containing, for example, the ending characters , . ; : / is coded as follows: 



DB 



5,C',.;:/' 
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Code 19 - Peek 



This call permits the task to extract certain system and task-dependent information from system tables. This information is 
moved to the caller's parameter block, which is 26 bytes long. Tlie format is illustrated in Figure 3-1. 



0(0) 


00 


1(1) 


19 


2(2) 


NLIJ 


3(3) 


MPRI 


4(4) 




OSID 






\i(C) 




TASK ID 




- 


20(14) 


CTSW 




22(16) 


TASK OPTIONS 




24(18) 


TASK STATUS 













Figure 3-1 . SVC 2 Code 1 9 Parameter Block 

The firet two bytes of the parameter block are set by the user program and indicate SVC 2 code 19. The remaining lieids 
are filled in by OS/16 and have the following meanings: 



NLU 


Number of LUs available to the task. 




MPRI 


Maximum priority of the task. 




OSID 


Eight ASCII characters of the form "OS/16MT2r" where r is numeric and indicates tlie 
Icvel of tlie OS/ 16 MT2 system. 


revision 


TASK ID 


Eight-character ASCII Task Identifier. 




CTSW 


Status field (upper 16 bits) of the task's current Task Status Word. 




TASK OPTIONS 


The Options halfword from the task's TCB. 




TASK STATUS 


The status halfword from the task's TCB. 





This parameter must be on a Italfword boundary in a writable segment and may be coded as follows: 





ALIGN 


1 

Z. 


PARBLK 


DB 


0,19 




DS 


24 



NOTE 

This parameter block must be 26 bytes long if information follow- 
ing it is not to be overwritten. 

Code 23 — Timer Management 

This call permits the user to set up a time interval, and either to wait for that interval, or to cause an item to be added to 
the task's Task Queue when the interval is complete.. Through the trap capability, it provides a very useful mechanism for 
service of periodic functions. This call also permits the user to cancel an outstanding time interval. 

The parameter block has the following format: 



ALIGN 
DB 
DC 
DC 


2 
OPTIONS,23 

h'reg' 

Y'TIME' 


DESIRED OPTIONS 

REGISTER CONTAINING PARAMETER 

TIME FIELD 



Bits 0-3 (TT) of the TIME field indicate the type of interval desired. The defined codes are; 

0000 Seconds since midnight (Time of day interval) 

0001 Milliseconds from now (Elapsed time interval) 
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3-15 



All other codes are considered illegal, and cause an Illegal SVC error. 

Bits 4-3 1 of the TIME field contain the number of clock ticks in the interval. This number can be no greater than 22^-1 , 
(268,435,455 decimal, OFFFFFFF hexadecimal). A clock tick is a second if TT=0000 or a millisecond if TT=0001. 

Options recognized are as follows: 



X'80' 
X'lO' 



Add to Queue on completion of interval 
Wait until completion of interval 
Cancel time interval 



If the Wait option is selected, the REG field of the parameter block is ignored. The task enters a time Wait state and does 
not leave it until the completion of the interval. 

If the Add to Queue option is selected, the REG field of the parameter block contains the number of one of the user's 
general registers. This register contains a parameter that is to be added to the user's Task Queue on completion of the 
interval. A task may have only one active interval at any time. If a second interval is specified, it overrides the first. A time 
interval, once activated, cannot be deactivated unless the task goes to EOT before the interval is complete or a Cancel Time 
Interval is issued. 

If the Cancel Time Interval option is selected, the REG and TIME fields of the parameter block are ignored. The 
outstanding time interval is cancelled and the Condition Code is set to zero. If no such interval is found, the V-bit of the 
I Condition Code is set (CC=4). The occurrence of a power fail/restore cancels all outstanding time intervals. 



SVC 3 - END OF TASK (EOT) 

This call permits a task to terminate itself in an orderly fashion. Its format is: 

SVC 3,N EOT 

There is no parameter block associated with this call. Instead, the effective address of the second argument. N, is treated as 
a binary constant, and replaces the Return Code used by the Command Substitution System (CSS) (see the OS/ 16 MT2 
Operator's Manual). 

Return Codes may be treated as desired by the user in CSS conditional testing; however, the CSS system assumes that 
Return Code represents normal termination, 255 represents termination by the system or another task (Cancel). 

If the task issuing this call has I/O in progress at the time the call is made, the I/O is terminated. Write operations are 
permitted to terminate normally, while Read operations are aborted. 

If the task issuing this call is a nonresident task, its Logical Units are all closed, and it is removed from memory. If, how- 
ever, the task issuing this call is a resident task, its files are checkpointed, but not closed, and it is not removed from 
memory. 

N may consist of an indexed operand; e.g., 0(R1). In this case the Return Code is set to the sum of the contents of the 
specified register and the displacement. 

SVC S -^ FETCH OVERLAY 

Tliis call permits a task to fetch an overlay from a specified Logical Unit. The format of the parameter block is as follows: 





ALIGN 


2 




PARBLK 


DC 


C'OVLYNM' 


OVERLAY NAME (6 characters) 




DS 


2 


RESERVED FOR OS/32 COMPATIBILITY 




DB 





STATUS 




DB 


OPTIONS 


OPTIONS 




DC 


h'lu' 


LU NUMBER 



3-16 
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Options recognized are: 

X'Ol' Load from LU without positioning 

X 04 Load from LU after rewind 

Any other value in the OPTIONS byte is considered illegal and results in an Illegal SVC error. 

llie status returned is: 

X'OO' Overlay loaded successfully 

X'lO' Load failed (for various possible reasons) 

X'20' Mismatch on overlay name 

X'40 Overlay would not fit in allocated memory 

The overlay file must be assigned to the Logical Unit specified in the parameter block. This file must be prepared by the 
OS/16 Task Establisher Task (TET/16). Sec Chapter 5 of the OSI16 MT2 Operator's Manual for the appropriate discussion 
of preparing tasks with overlays. The specified overlay name is checked against the name in the Loader Information Block 
of the overlay file; if it does not match, an error status is returned. 

The calling program does not resume execution until the overlay is loaded. If the overlay is successfully loaded, the root 
program may Branch and Link to it as a subroutine. See Chapter 7 for a discussion of overlay facilities provided by 
TET/16. 

If Load without positioning is specified, the file must be positioned at the LIB of the overlay to be loaded. 

On return, the overlay file or device is positioned to the logical record following the last logical record containing the 
overlay. 

The parameter block must be in a writable segment. 



NOTE 

OPTION COMP affects the SVC 5 parameter Block. When OPTION 
COMP is used, the "DS 2" following the 6 character overlay name 
should not be specified. 

SVC 6 ~ INTERTASK COORDINATION 

SVC 6 provides facilities for foreground tasks to invoke and communicate with other tasks. 

SVC 6 functions include the ability to: 

Load a task 

Start a task 

Cancel a task 

Queue a parameter to a task 

Change a task's priority 

Control Trap Generating Devices 

Make a task memory resident or non-Memory Resident 

Send a message to a task 

The SVC 6 parameter block is 38 bytes long and must start on a halfword boundary in a writable segment. The format is 
illustrated in Figure 3-2. 
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0(0) 






TASK ID 


8(8) 






FUNCTION CODE 


12(C) 






TASK STATUS 


14(E) 






ERROR STATUS 


16(10) 


LOAD LU 




17(11) 

PRIORITY 


18(12) 


RPRl 






19(13) 

RESERVED 


20(14) 






START ADDRESS 


22(16) 

TT 






DELAY TIME 


26(1 A) 






DEVICE MNEMONIC 


30(1E) 






PARAMETER 


32(20) 




MESSAGE BUFFER ADDRESS 


34(22) 






RESERVED (4 BYTES) 



Figure 3-2. SVC 6 Parameter Block 

The meaning of each field is explained in the description of each function requiring that field. Table 3-5 summarizes the 
use of each field. The parameter block may be coded: 





ALIGN 


2 




PARBLK 


DC 


c'taskid' 


TASKID (8 bytes) 




DC 


Y' function' 


FUNCTION CODE 




DS 


4 


TASK ERROR STATUS 




DB 


LU 


LOAD LU 




DB 


PRI 


PRIORITY 




DS 


2 


RPRI/RESERVED 




DC 


A(START) 


START ADDRESS 




DC 


y'time' 


TIME DELAY 




DC 


c'devm' 


DEVICE MNEMONIC 




DC 


X'PARM' 


PARAMETER 




DC 


A{MESSAGE) 


MESSAGE BUFFER ADDRESS 




DS 


4 


RESERVED 



Although not all fields are used by each function, the full SVC 6 parameter block must be reserved. 
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TABLE 3-5. SVC 6 PARAMETER BLOCK FIELDS 



FIELD 


NAIVIE 


MEANING 


Bytes 






0-7 


Task ID 


Name of task; not required if call is self-directed. 


8-11 


Function Code 


Specifies desired functions; See Table 3-6. 


12-13 


Task Status 


The wait status halfword of the specified task is returned by the system in this 
field. 


14-15 


Error Status 


Set to ZERO for normal termination or to error code if error detected. See Table 
3-7. 


16 


Load LU 


Specifies LU from which to load the task. Used only for Load function. 


17 


Priority 


Specifies priority for change priority function. May not be 255 (E-tasks). Must be 
in range 10-249 (U-tasks|. 


18 


RPRI 


Set by system to actual priority of specified task. 


19 




(reserved) 


20-21 


Start Address 


Used only for START functions; specifies address at which to start specified task. If 
ZERO, signifies normal transfer address, as specified at TET/16 time. 


22 (Bits 0-3) 


TT 


Time Type: indicates type of time delay. Used only for Delay-Start. Legal codes 
are: 

0000 = seconds since midnight 0001 = milliseconds from now. 


22-25 




Specifies number of seconds or milliseconds, as defined by TT field, to delay the 


(Bits 4-31) 


Delay Time 


start operation. Used only for Delay-Start. 


26-29 


Device Mnemonic 


Specifies device affected by Connect, Thaw, SINT, Freeze and Unconnect 
functions. (See Table 3-6). 


30-31 


Parameter 


Specifies parameter to be queued for Queue parameter function; specifies device 
parameter for Connect functions. 


32-33 


A((Vlessage) 


Specifies address of message buffer for Send Message Function. 


34-37 




(Reserved) 



Task ID and Function Code 

The Task ID field specifies tlie name of the task at which the SVC 6 is directed. A Task ID must either be .BG for the 
background task or must consist of alphanumeric characters with the first character alphabetic. If the call is directed at the 
calling task (see function code D field), it is termed a self-directed call and the Task ID field is not required. A function 
may also be directed at the calling task by specifying Other-Task in the function code and the calling task's name in the 
Task ID field. The function code specifies the functions to be performed on the specified task. Each bit in the function 
specifics a separate function. The functions specified are performed in the order of designated bits from left to riglit. The 
definition of the function code bit assignments is given in Table 3-6. 
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Errors 

If an error is detected in the performance of any requested function, an error status is returned and no further functions 
are performed. Since the Error Status field contains an indicator of which function was being performed at the time of 
error, it is always possible for the calling task to determine the functions that were performed and those that were not. 

The format of the Error Status halfword is as follows: 



BIT 







7 


8 




15 


NAME 


Position Pointer 


Error Code 



The Position Pointer points to the field in the Function Code fullword that was being processed at the time the error was 
detected. This pointer takes the form of a bit pointer which may have values in the range through 31. The possible values 
of the Error Code field are detailed in Table 3-7. 

Status Return 

No matter what functions are specified, and except for Error Code 4 (no such task), the Wait Status halfword and the 
current priority from the specified task's TCB are always returned in the Task Status and RPRI fields. This allows the 
calling task to restore the specified task to its previous priority. If only a status return is desired, it is permissible to set no 
bits in the function code (except for the Direction field). The entire SVC 6 call is then treated as a Null operation, but the 
status and priority are returned as usual. 
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TABLE 3-6. SVC 6 FUNCTION CODES 



00000000001 11 11 11 11 122222222223 3 
01234567890 1234567890123456789 _ L 

Id I E I I L I IhI iMlalPl lolThlFlu I In | T 



BIT(S) 


NAME 


HEX 


MASK 


MEANING 


0-1 


D 


8000 


0000 


DIRECTION: 00,01 = Illegal codes 






COOO 


0000 


10 = Other Task 

11 =self 


2-3 


E 


0000 


0000 


END TASK: 00 = no function requested 






1000 


0000 


01 = cancel 






2000 


0000 


10 = delete 






3000 


0000 


1 1 = delete 


4-5 








RESERVED (SET TO ZERO) 


6 


L 


0200 


0000 


LOAD TASK 


7 




0100 


0000 


TASK TO BE LOADED ONLY IN ESTABLISHED PARTITION. 


8 


H 


0080 


0000 


TASK RESIDENT 


9-10 








RESERVED (SET TO ZERO) 


11 


M 


0010 


0000 


SEND MESSAGE 


12 


Q 


0008 


0000 


ADD PARAMETER TO SPECIFIED TASK'S TASK QUEUE. 


13 


P 


0004 


0000 


CHANGE PRIORITY OF SPECIFIED TASK. 


14-15 








RESERVED. (SET TO ZERO) 


16 





0000 


8000 


CONNECT: CONNECT SPECIFIED DEVICE TO SPECIFIED TASK. 


17 


T 


0000 


4000 


THAW: ENABLE INTERRUPTS ON SPECIFIED DEVICE. 


18 


1 


0000 


2000 


SINT: SIMULATE INTERRUPT ON SPECIFIED DEVICE. 


19 


F 


0000 


1000 


FREEZE: DISABLE INTERRUPTS ON SPECIFIED DEVICE. 


20 


U 


0000 


0800 


UNCONNECT: DISCONNECT SPECIFIED DEVICE FROM 
SPECIFIED TASK. 


21-24 








RESERVED. (SET TO ZERO) 


25 


N 


0000 


0040 


TASK NON-RESIDENT 


26-28 








RESERVED (SET TO ZERO) 


29-30 


A 


0000 


0000 


START TASK: 00 = no function requested 






0000 


0002 


01 = start immediately 






0000 


0004 


10 = delay start 






0000 


0006 


11 = delay start 


31 








RESERVED (SET TO ZERO) 
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TABLE 3-7. SVC 6 ERROR CODES 



Code Dec 






(Hex) 


Function(s) 


Meaning 


0(0) 


All 


No errors; all requested functions complete. 


1(1) 


All 


Syntax error in Task ID field. Does not apply to 
self-directed calls. 


2(2) 


— 


Illegal function code. 


3(3) 


L 


Task already present. 


4(4) 


All but L 


No such task in foreground. 


5(5) 


P 


Invalid priority. 


6(6) 


L 


Floating point not supported by SYSGEN. 


7(7) 


A 


Specified task not dormant. 


8(8) 


S 


Invalid Start address. 


10(A) 


A (delay) 


Invalid code in TT field. 


11(B) 


M 


Message not sent (Task unable to receive) 


12(C) 


Q 


No queue, full queue, or entries disabled. 


13(D) 


0,T,l,F,U 


No such device in system. 


14(E) 


0,T,l,F,U 


Device named is not a connectable device. 


15(F) 





Device is busy, cannot connect. 


16(10) 


T.I.F.U 


Device not connected to specified task. 


17(11) 


L 


Invalid or unassigned Load LU. 


18(12) 


L 


Checksum error. 


25(19) 


1 


Device is not SINTable. 


66(42) 


L 


Resident Library or Task Common not present. 


68(44) 


L 


Invalid format on Loader Information Block. 


73(49) 


L 


Partition not vacant. 


74(4A) 


L 


I/O error on ROLL OUT. 


75(4B) 


L 


Assign/Close error on ROLL OUT. 


76{4C) 


L 


Partition does not exist. 


129-192 


L 


I/O error reading Load LU; error status is as returned by SVC 1. 


(81-.C01 
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End Task Function 

Task ID and Function Code are the required fields. 

This function causes the specified task to terminate as though it had executed an 

SVC 3,255. 

The Return Code of 255 indicates abnormal termination. If Delete is specified, the task is made nonresident and then 
cancelled. This causes it to be removed from memory. If Cancel is specified, the task is removed from memory only if it is 
a nonresident foreground task. If this call is self-directed, SVC 6 processing is terminated. It is not permissible to specify 
this function with a LOAD or START since this is a proceed function. 

Load Task Function 

Task ID, Function Code and Load LU are the required fields. 

The specified task is loaded from the Load LU. If a task is already present in the system with the given Task ID or the Task 
ID is invahd, the call is rejected. A self-directed load request is also rejected. 

The task to be loaded must have been processed with the OS/ 16 Task Establisher Task (TET/16), The Loader Information 
Block (LIB) is read from the specified LU which must have been previously assigned and positioned to the LIB. A 
partition required by the task (determined at TET/16 time) is checked to see if it is vacant, or contains a reliable task of 
lower priority. If not, the call is rejected. Upon loading the task, it is given the name found in the TASKID field. 

On successful return from this call, the specified file or device is positioned after the loaded task. 

Send Message Function 

Task Id, Function Code and Message Buffer Address are the required fields. 

This function provides the calling task with the capability of sending a message to the called task. The task to which a 
message is directed must have been set up to receive messages. On request, a message set up in the calling task is accessed 
by the system as 64 bytes of data. The Task Id of the calUng task is appended as a header and a 72 byte message is passed 
to the receiving task. If the receiving of messages by that task is disabled an error status is returned. The receiving task 
must not be dormant. 

The Message Buffer must be on a halfword boundary. The actual message may be less than 64 bytes even though 64 bytes 
will be sent. No checking or formatiing of the message performed. Refer to the section further in this chapter entitled 
"Sending and Receiving Task Messages" for more information. 

Queue Parameter Function 

Task ID, Function Code and Parameter are the required fields. 

The parameter specified in the PARAMETER field of the parameter block is added to the specified task's Task Queue, if; 

- the specified task has a Task Queue; 

- that queue is not full; and 

- the specified task's TSW enables entries to the Queue. 

- the specified task is not dormant. 

Otherwise, the call is rejected with appropriate error status. 

Change Priority Function 

Task ID, Function Code and Priority are the required fields. 

This function changes the priority of the specified task from whatever it was before the call to the priority specified in the 
PRIORITY field of the parameter block. The call is rejected for U-tasks if the priority specified is outside the valid range 
of 10-249. 

If the specified priority is greater than the established maximum priority of the specified task then the established 
maximum priority is used instead of the specified priority. This is not considered an error. RPRI is set to the priority of 
the task before it is changed. 



I 
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Task Resident and Non-Resident Functions 

Task ID and Function Code are the required fields. 

Tlie Task Resident function makes the specified task memory resident. The Task Non-Resident function makes the 
specified task non-memory resident, allowing the task to be deleted when it goes to End of Task. Specifying Task 
Non-Resident and End Task does not delete the specified task because the task is cancelled and then is set Non-Resident. 

Trap-Generating Device Functions 

The functions Connect, Thaw, SINT, Freeze and Unconnect are provided for the control of Trap-Generating Devices 
(TGD). These functions all use the DEVICE MNEMONIC field of the parameter block. This field must contain the 
mnemonic of a TGD. For all functions except Connect, a test is made to make sure that the specified TGD is connected to 
the specified task. 

A TGD may not be connected to more than one task at a time; however, a task may have any number of TGDs connected 
to it. The parameter that is placed in the Task Queue on a TGD interrupt can be used to differentiate between multiple 
TGDs connected to a task. 

Connect 

Task ID, Function Code, Device Mnemonic and Parameter are the required fields. 

This function connects the TGD specified by DEVICE MNEMONIC to the specified task. The named device must be a 
TGD; it must not be connected to any other task, or already connected to the same task. The parameter specified by 
PARAMETER becomes associated with the TGD; this parameter is placed in the specified task's Task Queue when an 
interrupt occurs. Interrupts are not enabled by this call; a Thaw call must be used to enable interrupts. 

Thaw 

Task ID, Function Code and Device Mnemonic are the required fields. 

This function enables interrupts on the specified TGD. The TGD is first checked to make sure that it is connected to the 
specified task. Once enabled, interrupts on this device may be disabled only by a Freeze or Unconnect call, or by the task 
going to EOT. This call has no effect if interrupts are already Thawed. 

SINT 

Task ID, Function Code and Device Mnemonic are the required fields. 

This function simulates an interrupt on the specified TGD. The device must be connected to the specified task and it must 
be a SINTable TGD. (Not all TGD drivers are capable of accepting a SINT call; see Chapter 8). If device interrupts have not 
been enabled by means of a Thaw call, the SINT call is ignored. This condition is not treated as an error. 

Freeze 

Task ID, Function Code and Device Mnemonic are the required fields. 

This function disables interrupts on the specified TGD. It does not disconnect the device from the task. Note that 
interrupts are not queued while the TGD is in a frozen state. This call has no effect if interrupts are already frozen. 

Unconnect 

Task ID, Function Code and Device Mnemonic are the required fields. 

This function detaches the specified TGD from the specified task. If the device is in a Thawed state, its interrupts are 
disabled. The device is now free to be Connected to any other task. 
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Start Task Function 

Task ID, Function Code and Start Address are the required fields. TT and Delay Time may optionally be specified. 

This call causes the named tpsk to be started. The address at which it is to be started is specified by the START ADDRESS 
parameter. If this field is non-zero, it indicates the address at which to start the task. If this field contains zero, the task is 
started at its established transfer address. If this field contains an address tliat is not within the specified task's memory, an 
error is returned by SVC 6. 

This call is rejected if the specified task is not in a Dormant or Console Wait state. No implied-load facility is provided by 
this call; therefore, the specified task must be present in memory at the time of the call. It is permissible, of course, to 
specify both Load and Start functions in the same call, since the Start field is not processed until after the Load field 
processing is complete. 

If Delay-Start is selected, the TT and DELAY TIME fields of the parameter block are used to determine the length and 
type of the delay. The specified task is actually started, but is placed immediately in a Time Wait or Interval Wait state. 

This call is rejected if it is self-directed. 

Sending and Receiving Task Messages 

A task which is fully prepared to receive message(s) will have enabled queue entries on send requests from other tasks, and 
have set up a receiving buffer address in its UDL area. The task is not limited to one message buffer; it can set up a chain or 
ring of buffers so that a number of messages can be received. 

Each receiving buffer must be 74 bytes long. 



1 


2 9 


10 73 


LINK 


TASKID 


MESSAGE 



where, LINK is the link address (2 bytes) which points to next buffer or is zero to indicate last buffer in chain. 

The least significant bit (i.e., X'OOOl ') is used as a marker bit, since the true address is known to be even. This marker bit 
is: 

1 . Initialized zero by the task 

2. Set by the system when a message is sent to indicate buffer full 

3. Cleared by the task when the message is processed to indicate buffer empty 
Tlie TASKID field is an 8 byte Task Id of sending task and the MESSAGE field is a 64 byte message. 
To receive messages a task must do the following; 

1 . Enable queue entries on send message by setting bit 1 1 in the current TSW. This enable bit is declared 
in the UDL STRUC (See Chapter 5) as: 

TSW.PMM EQU X'OOIO' Queue Send Message 

2. Set up a message buffer structure consisting of one or more 74 byte buffers. The address of the first 
buffer is declared in the UDL. This item is declared in the UDL STRUC as: 

UDL.MSGR DS 2 A(Message Buffer) 

Link addresses must also be set up at the beginning of each buffer. 

The task can take a trap whenever a message is received. Task Queue Service Traps are enabled by Setting bit 4 in the 
current TSW. This enable bit is declared in the UDL STRUC as: 

TSW.QSM EQU X'0800' Queue Service Trap Enable 
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On a send message request, the system first verifies that the receiving task is in the system and checks its current Task 
Status Word (TSW) to determine whether queue entry on send message is enabled. If not, it returns an error status. If 
enabled, the receiving buffer address is checked for being within the memory limits of the task. If zero (indicating no 
available buffer), or least significant bit is set (indicating the buffer is already full), or illegal, the system returns an error 
status. 

If a buffer is available, the system stores the Task Id of the sending task in bytes 3 to 10, gets the message start address 
from the SVC parameter block, and moves 64 characters into bytes 10 to 73. The marker bit in the link address field is set 
to indicate that the buffer is full. The address of the buffer is added to the task's Task Queue, and the link address is placed 
in the receiving task's UDL to point to the next available buffer. 



Message Buffer Structures 

The mechanism for passing messages gives the receiving task a choice of Message Buffer Structures. Figure 3-3 outlines four 
possible structures. 



Single-Buffer Ring 

When the buffer is empty, the link field indicating the next message buffer points to itself, and the least significant marker 
bit is zero. When a message is received, the link field is moved into the UDL as A(MESSAGE RING) and the marker bit is 
set to 1. This inhibits further messages since the next buffer is already full. When the task has processed the message, it 
clears the marker bit to again enable the receiving of a message into the same buffer. 



Single-Buffer Chain 

Here the link field is zero to indicate no other buffers are available for the receiving of messages. On receipt of the first 
message, the zero link field is moved into the UDL, and will inhibit all subsequent messages. To enable messages, the 
receiving task must dynamically set up a new empty buffer address in the UDL. 



Multiple-Buffer Ring 

Initially, all link fields indicate an empty buffer. When buffer 1 is filled, A(MESSAGE RING) is set to a point to buffer 2. 
When buffer 2 is filled, A(MESSAGE RING) is set to a point to buffer 1 . If, by the time the next message is ready to be 
sent, buffer 1 has been processed by the receiving task, and the receiving task has set buffer 1 link field "empty", the 
message is placed in buffer 1. As long as the receiving task can process buffers as fast as they are being filled, no messages 
are lost and no "send message" requests are rejected. A multiple-buffer ring may consist of as many buffers as the user task 
desires. The link field of each buffer is set to point to the next buffer; that of the last buffer is set to point to the first. 



Multiple-Buffer Chain 

This structure is similar to that of the multiple-buffer ring, with the exception that the link field of the last buffer is set to 
zero. When the last buffer is filled by the system, A(MESSAGE RING) is set to zero, inhibiting the sending of further 
messages. This structure is of value if the receiving task is dynamically acquiring buffers from a pool within itself. Processed 
buffers are released from the chain and new buffers added to its end. If new buffers can be acquired as fast as the system 
fills them, no messages are lost. 
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A (MESSAGE RING) 

IN UDL 
BUFFER 



A (MESSAGE RING) 

IN UDL 
BUFFER 



A (MESSAGE RING) 

UDL 
BUFFER 1 




A(BUFFER) 




(a) Single-Buffer Ring 




(b) Single-Buffer Chain 



A(BUFFER 1) 



A(BUFFER2) 



DATA AREA 



BUFFER 2 



A(BUFFER 1) 



DATA AREA 




(c) Multiple-Buffer Ring 



A(MESSAGE RING) 

IN UDL 
BUFFER 1 



A(BUFFER 1) 



A(BUFFER2) 



DATA AREA 



BUFFER 2 



DATA AREA 



(d) Multiple-Buffer Chain 



Figure 3-3. Message Buffer Structures 
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SVC 7 - FILE MANAGEMENT SERVICES 

This call gives the user facilities for manipulation of files and devices. The facilities provided are: 

Allocation (creation) of direct-access flies; 

Assignment of files and devices to Logical Units (LUs); 

Modification of access privileges on existing assignments; 

Renaming of files; 

Modification of files' protection keys; 

Qosing (deassignment) of assigned files and devices; 

Deletion of direct-access files; 

Checkpointing of assigned files; 

Examination of attributes of assigned files and devices. 

ITie format of the SVC 7 Parameter Block, which must be on a halfword boundary in a writable logical segment is 
illustrated in Figure 3-4. 



0(0) 

CMD 


1(1) 

MOD 


2(2) 

STAT 


3(3) 

LU 


4(4) 

WKEY 


5(5) 

RKEY 


6(6) LOGICAL 

RECORD LENGTH (LRECL) 


8(8) 


VOLUME ID OR DEVICE MNEMONIC 


12(C) 


FILENAME 


20(14) 


EXTENSION 


23(17) 

(RESERVED) 


24(18) 


SIZE 



Figure 3-4. SVC 7 Parameter Block 



The meaning and use of each field is explained in the description of each function requiring that field. The parameter block 
may be coded: 





ALIGN 


2 




PARBLK 


DB 


CMD 


COMMAND 




DB 


MOD 


MODIFIER 




DB 





STATUS 




DB 


LU 


LU 




DB 


WKEY 


WRITE KEY 




DB 


RKEY 


READ KEY 




DC 


h'lrecl' 


LOGICAL RECORD LENGTH 




DC 


C'VOLN' 


VOLUME 




DC 


c'filename' 


FILE NAME 




DC 


C'EXT' 


EXTENSION 




DC 


Y'SIZE' 


SIZE 



SVC 7 Parameter Block Fields 

Command/Modifier 

The format of the Command/Modifier Halfword is shown in Figure 3-5. 
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BIT 





1 


2 


3 


4 


5 


6 


7 8 


10 11 


12 13 


15 


NAME 


A 





H 


N 


P 


C 


D 


T 


AP 




BM 




FT 



COMMANDS 



Bits 



8-10 



11-12 



13-15 



Name 



A 
O 

H 
N 
P 
C 

D 

T 

AP 



BM 



FT 



Hex Mask 



8000 
4000 
2000 
1000 
0800 
0400 
0200 
0100 



MODIFIERS 



Meaning 



0000 
0020 
0040 
0060 
0080 
OOAO 
OOCO 

OOEO 

0000 
0008 
0010 
0018 

0000 
0001 
0002 
0003 

0007 



Allocate - requires file type (FT) modifier 

Assign - requires access privilege (AP) and buffer management (BM) modifiers 

Change Access Privilege - requires access privilege (AP) modifiers 

Rename - no modifiers 

Reprotect - no modifiers 

Close - no modifiers 

Delete - no modifiers 

Checkpoint - no modifiers 

Bits 0-7 all zero = Fetch Attributes (F) 

Access Privileges 

SRO- Shared Read Only 

ERO - Exclusive Read Only 

SWO - Shared Write Only 

EWO - Exclusive Write Only 

SRW - Shared Read-Write 

SREW - Shared Read-Exclusive Write 

ERSW - Exclusive Read-Shared Write 

ERW - Exclusive Read-Write 

Buffer Management 

Default Buffer Management 

Unbuffered (Physical) 

Buffered (Logical) 

Reserved 

File Type 

Contiguous 

Reserved (considered Illegal) 

Indexed 

Reserved (considered illegal) 



Figure 3-5. SVC 7 Command/Modifier Halfword 
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Command 

The Command bits are processed sequentially from left to right. If Bits 0-7 are all ZERO, a Fetch Attributes function is 
specified. The specific functions are described in the following paragraphs. 

Access Privileges 

Access privileges are necessary for Assign and Change Access Privilege calls. This field is ignored for all other functions If 
Bits 8-10 are all ZERO, Shared Read Only (SRO) is specified. 

Buffer Management 

The default buffer management methods are Unbuffered for Contiguous File Type and Buffered for Indexed File Type. In 
OS/16 MT2, this field is ignored and the default is always used. For a Fetch Attributes call, the device code is returned to 
the Modifier byte of the Command/Modifier halfword. 

Status 

The interpretation of the status field depends on the functions specified in the call and is defined under the description of 
each command. A status of zero always means the desired options were performed without error. A summary of all 
possible error codes is given in Table 3-8 for reference. 



TABLE 3-8. SVC 7 STATUS BYTE 



ERROR CODE 
DEC (HEX) 



129-192 
(81-CO) 



FUNCTION 



0(00) 


ALL 


1 <01) 


A,0,D 


2(02) 


All but A,D 


3(03) 


A,0,D 


4(04) 


A.O.N.D 


5(05) 


A,0 


6(06) 


0,P,D 


7(07) 


AllbutC.T.F 


8(08) 





9(09) 


All but A 


10 (OA) 


A,0,N.P,D 


11 (OB) 


A,O.N.D 


12 (OC) 





13(0D) 


C 



All but F 



MEANING 



No error, the requested functions are complete. 

Illegal function. Illegal file type 

LU error; illegal LU 

Volume error; no such volume/device in system. 

Name error; mismatch on filename or extension field. 

Size error; erroneous LRECL or size field or no room on disc. 

Protect error; erroneous protection keys. 

Privilege error; unable to obtain requested privilege. 

Buffer error; no room in system for file control blocks or buffers. 

Assignment error; LU not assigned. 

Type error; non-direct access device, or device off-line. 

File Descriptor error; Illegal syntax. 

Attempt to assign SVC 6 connectable device. 

A spool file was closed and the Spooler was not able to receive 
the indication that the file was closed. 

I/O error; interpreted as SVC 1 status byte. 



The first error detected causes the SVC to return. If multiple functions were specified (e.g., Allocate and Assign) some 
tuncfaons may have been properiy performed (always in left-to-right sequence). 

LU Field 

This byte defines the Logical Unit used for all the SVC 7 functions except Allocate and Delete. 
Write Key And Read Key 

Protection keys for devices and Direct-Access files are specified in this halfword. These keys are required for the Allocate 
^tX'tef^"™''"'^' ^"'' ^^^^^^ ^""''"''"'- '^'^ ^'^^^ '" "'^^ ^y *« P'^tch Attributes call to return the device or file 
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Logical Record Length (LRECL) 

This halfword field, on an Allocate call, must contain the logical record length for a buffered file. On a Fetch Attributes 
call, the logical record length of a file or physical record length of a device is returned in this field. If ZERO is returned, 
device or file has a variable record length. LRECL is not used for other functions. 

Volume ID (VOLN) or Device Mnemonic 

This four-byte field identifies the volume if it is a Direct-Access file, or the device mnemonic if it is a device. This field of 
ASCII characters is required for the Allocate, Assign, and Delete. 

VOLN together with FILENAME and EXT fields specify a File Descriptor. The volume name or device name, as the case 
may be, is returned by the system on a Fetch Attributes call in the VOLN field. 

Filename 

This eight-byte field identifies the file on a Direct-Access device; it is ignored for a device. The user must specify the 
filename in ASCII characters for Allocate, Assign, Rename, and Delete calls. The filename is returned by the system on a 
Fetch Attributes call; it is blank for a device. 

Extension 

This three-byte ASCII field identifies the file type (e.g., OBJ, TSK, CSS, etc.), on a Direct-Access file. It is treated as an 
extension of, and is required under the same conditions as, the FILENAME. The byte following this field is ignored. | 

Size 

This fuUword field, on the Allocate call, must contain the file size in sectors for a Contiguous file, or the data block size 
(Bits 0-15) and index block size (Bits 1 6-3 1 ), in sectors for an Indexed file. On a Fetch Attributes call, this field is used to 
return the current size of a file, or buffer size in bytes for a communications terminal; size is unchanged for a device. For 
an Indexed file, size is in number of logical records; for contiguous files, it is in number of sectors. For a Direct-access 
device (E-Task only) this field returns the number of sectors on the device. 

SVC 7 Functions 

Allocate 

The Allocate function reserves space on a Direct-Access device and in the directory for the specified file type (FT). In the 
case of Indexed files, only a directory entry is reserved. The protection keys are entered in the directory. The required 
parameters are FT, KEYS, LRECL, VOLN, FILENAME, EXT and SIZE. 

Applicable error codes are : 



1(01) Illegal Function; an illegal file type was specified 

3(03) Volume Error; the specified volume was not mounted 

4(04) Name Error; the specified file name already exists on the specified volume 

5(05) Size Error; if a Contiguous file, there is not sufficient contiguous space on the specified 

volume to allocate a file of the specified size; if an Indexed file, there is insufficient space 
for a directory entry or invalid block size or logical record length specified. 

7(07) Privilege error; Disc is Write protected. 

10(0 A) Type Error; the specified volume is not a Direct- Access volume. 

1 1 (OB) File Descriptor Error; invalid syntax in volume name, file name or extension fields. 

129-192 I/O error. 

(81 -CO) 
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Assign 

The Assign function establislies a logical connection between a file (or device) and the task through a specified Logical 
Unit, under a given access privilege (AP) and using a given Buffer Management (BM) technique. The call is processed as 
follows: First the access privilege is examined to determine which protect key to check. The proper key is then checked 
against the keys in the file directory. The BM field is checked to see if the specified Buffer Management technique is valid 
for the type of file being assigned. The file is then assigned according to the requested access privileges. If SWO or EWO 
(Write Only) is specified, the file is positioned at its logical end (records are appended). Otherwise, the file is positioned at 
the beginning (record number = zero). For devices, only the keys are checked, for the given access privilege. 

Tlie required parameters are AP, BM, LU, KEYS, VOLN, FILENAME and EXT; BM, FILENAME and EXT fields are not 
used for devices. 

Applicable error codes are: 

1(01) Illegal function; attempt to assign invalid file type. 

2(02) LU Error; Illegal LU 

3(03) Volume Error; no such volume, Direct-Access device specified for U-Task 

4(04) Name Error; no such name on given volume 

5(05) Size error; no room on disc to allocate an index and a data block 

6(06) Protect Error; mismatch on protection keys 

7(07) Privilege Error; requested privilege may not be granted 

8(08) Buffer Error; no room for FCB or buffer 

9(09) LU Already Assigned 

lO(OA) Type Error; attempt to assign an off-line device to a U-Task. 

1 1 (OB) File Descriptor syntax error. 

1 2(0C) Attempt to assign a Trap Generating Device (TGD) 
129-192 (8 1 -CO) I/O Error 

NOTE 

A buffered file requires a buffer equal to the sum of the index and 
data block size of the file to be allocated in system space. The BM 
field is ignored in release 00 and 01; the default buffer manage- 
ment technique is used. 

Assigning an LU to the pseudo device for printer spooling causes allocation of an indexed disc file and assignment to the 
newly allocated file. 

Assigning the console device for shared read only (SRO) access causes an assignment to the console reader. 

Qiange Access Privileges 

Tliis function allows the user to change the current access privileges of a file or device which is assigned. Only two 
parameter fields in the SVC 7 Parameter Block arc required, the LU and AP portion of the modifier field. 

If an error is encountered while processing this request, the file remains assigned with its original access privilege. 
Applicable error codes are: 

2(02) LU Error; illegal LU 

7(07) Privilege Error; new privileges cannot be granted 

9(09) Assignment Error; LU not assigned 

129-192 (81 -CO) I/O Error 

Rename 

This function permits the name of an assigned file to be changed. The file must currently be assigned to the specified 
Logical Unit for Exclusive Read-Write (ERW). The required parameters are LU, FILENAME and EXT. The given LU must 
be assigned to a direct-access file (unless the caller is an Executive Task which may rename devices). The volume name field 
of the parameter block is ignored. The specified FILENAME.EXT replaces the previous FILENAME.EXT in the directory 
if the Rename function is successful . 

Applicable error codes are: 

2(02) LU Error; illegal LU 

4(04) Name Error; new name already exists on given volume 

7(07) Privilege Error; file not assigned for ERW 

9(09) Assignment Error; LU not assigned 

lO(OA) Type Error; LU assigned to a device (U-Task) or to the Null device (E-Task) 

1 1 (OB) File Descriptor Error 

129-192(81-C0) I/O Error 

Reprotect 

This function permits the protection keys of an assigned file to be changed. The required parameters are KEYS and LU. 
The given LU must be assigned to a Direct-Access file for Exclusive Read-Write (ERW) (unless the caller is an E-Task which 
may modify the protection keys of devices). If either the specified Read key or Write key is equal to X'FF', that key is 
ignored rather than changed (unless the caller is an E-Task). If the call is rejected, the previous keys remain unchanged. 
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Applicable error codes are: 



2(02) LU Error; illegal LU ^ ^ 

6(06) Protect Error, current key has value X'FF (U-Taslc only) 

7(07) Privilege Error; not assigned for ERW 

9(09) Assignment Error; LU not assigned 

lO(OA) Type Error; LU assigned to a device (U-Task) or to the Null or console device 

(E-Task) 

129- 192(81 -CO) I/O Error 

Qose 

This function discontinues an assigned logical connection between a task and a file or device. LU is the only required 
parameter. Tlie specified LU is deassigned. Files or buffered communications devices assigned for Write access have any 
partially filled buffers, written out by the Close call. The Close function issues an SVC 1 Wait Only call to ensure that any 
previous I/O Proceed calls are completed before deassigning. When a SPOOL file is closed, the file manager sends a message 
(via SVC 6) to the Spooler indicating that the file is available for printing. 

Applicable error codes are: 

2(02) LU Error; Illegal Logical Unit 

9(09) Assignment Error; LU not assigned 

13(0D) The Spooler was unable to receive the SVC 6 message. 

129-1 92(81 -CO) I/O Error 

Delete 

For a Delete function, the VOLN, FILENAME, EXT, and KEYS parameters must specify a Direct-Access file which is not 
currently assigned. If these conditions are met and both Read and Write keys match, the file is deleted from the directoi-y 
of its volume. Only an E-Task may delete a file with a key of X'FF'. 

Applicable error codes are: 

1(01 ) Illegal Function; attempt to delete invalid file type 

3(03) Volume Error; no such volume 

4(04) Name Error; file name does not exist on volume 

6(06) Protect Error; invalid protection keys 

7(07) Privilege Error; device write protected 

9(09) Assign Error; file currently assigned. 

lO(OA) Type Error; attempt to delete a device. 

1 1 (OB) File Descriptor Error 

I29-I92(81-C0) I/O Error 

Checkpoint 

The Checkpoint function permits the user to flush system Buffer Management buffers and to update the directory entry 
for a buffered file or communications device (e.g., BISYNC) on a given LU. LU is the only required parameter. Requesting 
a checkpoint for a non-buffered file or device has the same effect as an SVC 1 Wait Only call. 

The user may wish to employ Checkpointing after sensitive data is added to a buffered file because the logical blocking of 
data in memory in system buffers leaves the file vulnerable. The integrity of the data can be preserved on the file by 
Checkpointing. In case of system failure, all data on Indexed files up to the latest Close or Checkpoint operation is 
recoverable; data appended after the most recent Checkpoint is lost. Checkpoint differs from a Close/Assign sequence in 
that no repositioning is performed and that filename, access privileges, and keys need not be specified. 

The applicable error codes are: 

2(02) LU Error; illegal Logical Unit 

9(09) Assignment Error; LU not assigned 

129- 192(81 -CO) I/O Error 

Fetch Attributes 

Certain programs may require, for proper operation, knowledge of the physical attributes of the device or file associated 
with a given LU. For example, it might be desirable to know if random access is possible or if the device is rewindable. The 
Fetch Attributes function gives the user access to this information. 



The applicable error codes are: 



2(02) LU Error; Illegal LU 

9(09) Assignment Error; LU Not Assigned 
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Various fields within the SVC 7 parameter block are redefined for this call. When the command field is set to zero, 
indicating a Fetch Attributes call, the only required parameter is the Logical Unit. The system returns information in fields 
KEYS, LRECL, VOLN, FILENAME, EXT, SIZE and Modifier byte. 

The Write Key/Read Key halfword is redefined to receive an Attributes halfword as given in Table 3-9. Any bit set means 
the device or file supports the corresponding attributes. 



TABLE 3-9. SVC 7 DEVICE ATTRIBUTES HALFWORD 



BIT 




1 
2 
3 
4 
5 
6 
7 
8 

g 

10 
11 
12 
13 
14 
15 



ATTRIBUTES 



Interactive deuice 

Supports Read 

Supports Write 

Supports Binary 

Supports Wait I/O 

Supports Random 

Supports Unconditional Proceed 

Supports Image 

Supports Halt I/O 

Supports Rewind 

Supports Backspace Record 

Supports Forward Space Record 

Supports Write Filemark 

Supports Forward Space Filemark 

Supports Backspace Filemark 

Reserved 



The LRECL field is set by the system to the physical record length associated with the device (e.g., 80 for a card reader 
120 or 132 for a hne pnnter) if the record length is fixed; these two bytes are set to zero for a variable-record length 
device (e.g., magnetic tape). A TTY or CRT, which is in the strict sense a variable-record length device, normally has 
LKbCL set as though it were a fixed-record length device. This is because such a device is normally used in a fixed-record 
length method. Furthermore, a Contiguous Direct-Access file is considered to have a variable record length, whereas an 
Indexed file is considered to have a fixed record length, which is the logical record length specified for that file at the time 
of its allocation. 

The volume name, file name, and extension (VOLN:FILENAME.EXT) for a named file, or the device mnemonic for a 
device is returned m the File Descriptor portion of the parameter block. The program may use this information to provide 
the operator with intelligent information in case of error, to generate the name of a new output file by transformation on 
the name of the input file, etc. 

?f,'^c™^ ^'^^ °^ ^ Direct-Access file or current buffer size of a buffered communication device is returned in the SIZE 
tield; SIZE is unchanged for devices. The number of logical records is returned for an Indexed file; the number of sectors is 
returned for a Contiguous file. These sizes are returned as unsigned hexadecimal numbers. The extended device code for a 
communications device is returned in the high order halfword of the SIZE field. 

The Modifiers byte is set to indicate the file or device type. A sample of device codes is given in Table 3-10. Tlie codes for 
all supported devices are given in Chapter 8. 

Note that the full parameter block must be specified for the Fetch Attributes call or the system may overwrite the 
information following the parameter block. 
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TABLE 3-10. EXAMPLE DEVICE CODES 



CODE DEC (HEX) 



0(0) 
2(2) 
16(10) 
17(11) 
18(12) 
34(22) 
36(24) 
49(31) 
50(32) 
51 (33) 
52(34) 
64(40) 
65(41) 
66(42) 
80(50) 
81(51) 
82(52) 
96(60) 
97(61) 
112(70) 
114(72) 
255(FF) 



FILE OR DEVICE TYPE 



CONTIGUOUS FILE 

INDEXED FILE 

MODEL 33 TTY KEYBOARD/PRINTER 

MODEL 35 TTY KEYBOARD/PRINTER 

NONEDITING CRT ON CURRENT LOOP INTERFACE 

NONEDITING CRT ON LOCAL PASLA 

GRAPHIC DISPLAY TERMINAL ON LOCAL PASLA 

2.5 MBYTE REMOVABLE DISC CARTRIDGE 

10 MBYTE FIXED DISC CARTRIDGE 

10 MBYTE REMOVABLE DISC CARTRIDGE 

40 MBYTE REMOVABLE DISC CARTRIDGE 

800 BPI MAGNETIC TAPE 

1600 BPI MAGNETIC TAPE 

INTERTAPE CASSETTE 

HIGH SPEED PAPER TAPE READER/PUNCH 

MODEL 33 TTY READER/PUNCH 

MODEL 35 TTY READER/PUNCH 

CARD READER WITHOUT HOLLERITH/ASCII TRANSLATION 

CARD READER WITH HOLLERITH/ASCII TRANSLATION 

LOW SPEED LINE PRINTER 

HIGH SPEED LINE PRINTER 

NULL DEVICE 



SVC 9 - LOAD TSW 

This call is used to return from task-handled traps; it is also used to change trap enable/disable bits, to change queue entry 
enable/disable bits, and to enter Trap Wait. This is the task analogue of the machine-level LPSW instruction. 

The format of this call is; 

SVC 9, A(X2) 

The effective address of the SVC instruction specifies the location at which the new TSW is to be found on a halfword 
boundary in the task's address space. 

The effect of this instruction is to replace the Current Task Status Word found in the task's TCB with the indicated Task 
Status Word. Unless Trap Wait is specified in the new TSW, the task resumes executing instructions at the address specified 
by the LOC field of the new TSW. 

If the LOC field of the new TSW is zero, execution resumes at the instruction following the SVC 9. 
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CHAPTER 4 
GUIDE TO USING SVC 2 FACILITIES 



COMMAND PROCESSORS 

Command processors are a part of almost all utility programs and of many applications programs. Every time a program is 
written that has to accept directions from the outside, either by conversation with an operator or by job-control state- 
ments read from an input device, a command processor is required to interpret those directions. Consequently, command 
processors are constantly being written and rewritten, tested and retested; yet most command processors are so similar to 
each other that one could generally be put together out of a package of "canned" routines, if such a package were at hand. 

Some high-level languages, for example, SNOBOL, and certain versions of Extended BASIC, contain string-handling 
routines of sufficient sophistication as to render the writing of a command processor trivial. However, the assembly 
language programmer has no such facilities. 

One of the earliest functions of operating systems was to simplify the writing of I/O handling code. A logical extension to 
this concept is the provision, within the operating system, of a simple and well-defined method of using the operating 
system's own command processing routines. The INTERDATA OS/ 16 MT2 Operating System provides such a method. 

Tlie user of this method may find that the command language of a program is constrained to the use of certain formats if 
the operating system's command processor calls are chosen. These calls provide such a great range of capabilities, and are 
capable of such flexible use, as to make a slight restriction in formatting negligible in cost when compared to the savings in 
design, code and debug time that are realized by the use of these calls. 

Tliis chapter gives the user a guide to the use of the calls provided in OS/ 16 for command processing functions. 

COMMAND STATEMENT INPUT 

The Command Statement may be read via SVC 1 from any Logical Unit, or may be passed from one task to another. The 
important issue is how the Command Statement is handled once it is in the buffer. 

First, the buffer address is put into a given register. This register is used as the current buffer pointer during the entire 
command processing operation. All four command processing SVC 2 calls (Pack, Pack File Descriptor, Mnemonic Table 
Scan and Move ASCII Characters) expect to find the current buffer pointer in a register. The choice of which register to 
use is made by the user. 

Mnemonic Scan 

A Command Statement usually starts with some kind of mnemonic. This first mnemonic is generally called a verb because 
it tells what to do. 

OS/16 provides a call. Mnemonic Table Scan, which may be used to look for a match on any table of mnemonics. These 
mnemonics must be all alphabetic characters, except for the first character, which may be any ASCII character. Thus, 
SFRED is a valid mnemonic, but GLA2H is not. The mnemonic table is organized as a byte string. Each mnemonic in the 
table must be separated by one Null character (X'OO') from the following mnemonic. The table is terminated by two Null 
characters in a row. 

The OS/ 16 mnemonic syntax permits abbreviations. These are represented in the mnemonic table by flagging all required 
bytes of the mnemonic with Bit set to a 1. Non-required bytes have Bit set to 0. To represent the mnemonic APPEND, 
the code within the mnemonic table is: 



DB 


c'a'-hxV, c'p'-hx'so' 


required characters 


DB 


C'PEND' 


non-required characters 


DB 





end of mnemonic 
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In order to match a mnemonic table entry, the command string must match all required characters. If more alphabetics are 
present in the command string, they must match the non-required characters. If all required and non-required characters 
are exhausted and there are still more alphabetics in the command string, no match is recognized. 

For the example given previously, a legitimate match is found on: 

AP 

APP 

APPE 

APPEN 

APPEND 

AP2 (scan terminates on first non-alphabetic after first character) 

No match is found on: 



A 

APPENG 

APPENDIX 



(too short) 

(no match on non-required characters) 

(too long) 



The mnemonic table scan routine terminates as soon as it finds a non-alphabetic character in the command string. If a valid 
match is found at this point, an index number indicating the position within the mnemonic table of the matched 
mnemonic is returned. If no match is found, the index number is returned set to -1. The system does not check the 
separator (the non-alphabetic character that terminated the scan routine). This character must be checked by the user. The 
buffer pointer that was given to the system is returned pointing to the separator, if a match was found; it is returned 
unchanged if no match was found. Entries in the mnemonic table are counted from ZERO; that is, if a match was found on 
the third mnemonic in the table, the index is returned with a value of 2. 

Tlie condition code 'V bit is also set to show whether or not a match was found. It is set to if there was a match, or to 
1 (CC=4) if there was no match. 

A sample of how to use the Mnemonic Table Scan routine follows. Assume that the mnemonic table is to consist of four 
entries: SORT, MERGE, PRINT, and STOP. This table is coded as follows: 

MNMTAB DB C'S'+X'80', C'0'+X'80',C'RT',0 

DB C'M'+X'80',C'E'+X'80',C'RGE',0 

DB C'P'+X'80',C'R'+X'80',C'INT',0 

DB C'S'+X'80',C'T'+X'80',C'OP',0,0 

Notice the two bytes of ZERO ending the mnemonic table. If the command buffer pointer is found in register PNTR and 
the index is to be returned in register INDX, an SVC 2 parameter block to handle this table is coded as follows; 

SCAN DB 0,17,PNTR,INDX 

DC A(MNMTAB) 

Assume that a command line has just been read into a buffer named CMDBUF. Tlie verb is found as follows: 



FNDVB 



JTAB 



LDAI 


PNTR,CMDBUF 


SVC 


2,SCAN 


BO 


CMDERR 


SLLS 


INDX,LADC 


LDA 


INDX,JTAB(INDX) 


BR 


INDX 



DAC 



SORT, MERGE, PRINT, STOP 



set up buffer pointer 
scan the table 
branch if no match 
prepare for indexed branch 
get jump table address 
go to command executor 



This routine did not check the separator; if the characters SORT* had been in the command buffer, the result would have 
been the same as if SORT (Carriage Return) had been the command buffer content. Using this information, the code can 
be modified by taking advantage of the fact that PNTR points to the separator after a valid match. Assume that only a 
Carriage Return is allowed to follow the verb: 



FINDVB 


LDAI 


PNTR.CMDBUF 






SVC 


2,SCAN 






SLLS 


INDX.LADC 






BM 


CMDERR 


another way to test for error 




LIS 


WORK, X'OD' 


pick up a carriage return 




CLB 


WORK,0(PNTR) 


check the separator 




BNE 


CMDERR 






LDA 


INDX,JTAB(INDX) 






BR 


INDX 
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The results are better. If different separators are required for different verbs, however, the separator check should be done 
after the jump table branch. If no match is found, PNTR is not changed. If the proper mnemonic is not found, consult a 
different mnemonic table. The verb, in this particular syntax, may be optional and therefore has a default value. For 
example, in BASIC the verb is optional and defaults to LET. 

Operand Decoding 

Most command languages require operands for most of their verbs. The verb tells the processor what to do; the operands 
tell what to do it to, or how to do it. Operands in OS/ 16 MT2 command processor syntax are: 

Decimal numbers up to 65,535 

Hexadecimal numbers up to FFFFFFFF 

File Descriptors 

Mnemonics 

Arbitrary ASCII strings 

These are sufficient for most needs. If other forms of modifiers are required, they may be decoded by the user. 

Decimal and Hexadecimal Numbers 

The OS/ 16 MT2 Pack Numeric Data call allows decimal and hexadecimal numbers to be decoded. Options are provided 
either to skip, or not to skip, leading blanks. The current buffer pointer is required; this may be in the same register that 
was used for the MNEMONIC TABLE SCAN call. The result is always returned in Register 0. This call sets the Condition 
Code to indicate the status of the call. If too many digits were found, the 'V' flag is set (CC=4); if no digits were found, the 
L flag is set (CC=1). The first nontranslatable character found terminates the operation, and PNTR is set to point to that 
character, so that the separator can be checked easily. 

Tlie parameter block looks like one of the following (depending on options): 



PACKDEC 


DB 


X'80',15.0,PNTR 


decimal 


PACKHEX 


DB 


0,15,0,PNTR 


hexadecimal 


PACKDECS 


DB 


X'C0',15,0,PNTR 


decimal, skip leading blanks 


PACKHEXS 


DB 


X'40',15,0,PNTR 


hexadecimal, skip leading blanks 



Assume that the syntax of the rewind command were as follows: 

<rwdcmd> : := REW IND <lu> 
<lu> ::= <decimal number less than 256> 
And assume that the verb finder had found a match on REWIND and now wishes to find <lu>. This is done as follows: 



REWIND 



SVC 

BO 

BM 

CLHI 

BNL 

LIS 

CLB 

BNE 

STB 

SVC 



2,PACKDECS 

CMDERR 

CMDERR 

R0,256 

CMDERR 

WORK,X'0D' 

WORK,0(PNTR) 

CMDERR 

R0,RWDPBLK+1 

l.RWDPBLK 



get decimal number, skip blanks 
error if too many digits 
error if no digits 

error if number is too big 
check for carriage return 



rewind the lu 
continue 



Before stipulating "skip leading blanks", the number of leading blanks in the buffer must be considered, as the buffer may 
contain all blanks. The following resolves this problem: 



SVC 

CLAI 

BNL 



2,PACKDECS 

PNTR.BUFFEND 

CMDERR 



Another problem is now encountered: assume that <lu> were optional, with a default of ZERO. In that case, the BM 
CMDERR instruction should be omitted since the Pack call sets Register to ZERO if no digits are found. 
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File Descriptors 

This section does not apply to programs which do not perform any file or device handling; however, for systems using LU 
instead of device, this section points out the advantages of file and device handling. Under OS/ 16 MT2 it is easier to handle 
device and file names than it is to handle simple decimal numbers, because the system can do more error checkmg and 
default processing. 

The Pack File Descriptor call is used to handle device or file names. 

When Pack File Descriptor is called, it expedites decoding the entire syntax, including file name, volume name, extension, 
and separators; handles the optional cases and flags them; and expedites handling one common default case. The format of 
the parameter block is: 



PACKFD 


DB 
DC 


0,16,0,PNTR 
A(SV7PB+8) 


ordinary call 


PACKFDS 


DB 
DC 


X'40',17,0,PNTR 
A(SV7PB+8) 


skip leading blanks 


PACKFDN 


DB 
DC 


X'80',16,0,PNTR 
A(SV7PB+8) 


no volume default 


PACKFDNS 


DB 
DC 


X'C0',16,0,PNTR 
A(SV7PB+8) 


no default, skip bla 



As an example of how this call may be used, the syntax of the rewind command may be changed to: 
<rwdcmd> ::= REWIND <fd> 

A valid processing routine is: 



REWIND 


SVC 


2,PACKFDS 


pack fd and skip leading blanks 




BO 


CMDERR 


branch on syntax error 




CLAI 


PNTR,BUFFEND 






BNL 


CMDERR 


error if scan past end of buffer 




SVC 


7,SV7PB 


open the device or file on LU 




SVC 


1,RWD 


rewind the device 




SVC 


7, CLOSO 


close LU 
continue 


SV7PB 


DB 


X'40',0,0,0 


open LU 




DC 


Y"0" 






DS 


16 


File Descriptor field 


CLOSO 


DB 


X'04',0,0,0 


dose LU 


RWD 


DB 


X'CO', 0,0,0 


rewind LU 



In this example, SVC 1 or SVC 7 calls were not checked for errors, since the purpose of this demonstration does not 
concern use of SVC 1 or 7. A more difficult example is: 



<inputcmd> 



INPUT <fd> 



where the default volume name must be FRED and the default extension must be OBJ. Assume the verb INPUT has been 
detected and that the separator has not yet been checked. 



WORK 

INPUT 



PROCESS 

VOL 

EXT 



EQU 

LB 

CLHI 

BNE 

AIS 

LM 

STM 

SVC 

BO 

BNC 

LM 

STM 



DC 
DC 



14 

WORK,0(PNTR) 

WORK,C' ' 

CMDERR 

PNTR,1 

WORK, VOL 

WORK,SV7PB+8 

2,PACKFDN 

CMDERR 

PROCESS 

WORK,EXT 

WORK,SV7PB+20 

C'FRED' 
C'OBJ' 



check separator 



separator ok, increment pointer 
setup default volume 

pack fd , no skip, no default 
branch on syntax error 
branch unless default extension 
setup default extension 

continue 



44 
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The default volume name, FRED, was stored in the receiving area before the SVC 2 call. If the command strmg contamed a 
volume name, FRED is overlaid. If no volume name was present in the command string, since "no default" was specified, 
the volume name field of the receiving area is left unchanged. The extension default must be handled following an SVC 2 
call. 

The "no default" option is explained as follows: In any OS/16 MT2 system that has Direct-Access storage, there is a 
volume called the system default volume. This volume name may be changed by the console operator. Most commands to 
OS/ 16 MT2 itself assume that if no volume name is specified, the default volume is assumed. Therefore, the normal call to 
Pack File Descriptor stipulates default volume. If no volume ID is present in the File Descriptor string, OS/ 16 MT2 returns 
the name of the default volume, whatever it may be at the time, as though the user had typed it in. 

The reason for the no-default option is now clear. There are instances when the program may not wish to default to the 
name of the default volume, but rather to the last volume name that the user did type in, or perhaps to a volume name that 
the program specifically set up. If the program specifies no-default, the Pack File Descriptor routine assumes that the 
program has already set up the volume field of the receiving area for default condition. If the user does not enter a volume 
ID and the program has specified no-default, the volume field of the receiving area is left unchanged. 

The address field of the sample parameter block is defined as A(SV7PB-H8). Tills is because, when the PACK FILE 
DESCRIPTOR is called, the program desires the receiving area to be the File Descriptor field of an SVC 7 parameter block. 
This area is located 8 bytes past the start of the SVC 7 parameter block. It is not necessary to move tlie data directly into a 
parameter block. Note, however, that the receiving area must be 16 bytes long and must begin on a halfword boundary. 

This call sets condifion codes. The 'V' flag (CC=4) denotes a syntax error. The' L' flag (CC=1) denotes no volume ID. This 
flag is set whether or not no-default is specified. The 'C flag (CC=8) denotes no extension. If no extension is found, the 
system automatically gives a default extension of blanks. If use of a different default extension is desired, for example, 
OBJ, the'C'flag tells when to use it. If the blank extension is satisfactory as a default, the'C'flag may be ignored. The 'V,' 
flag should never be ignored, since the receiving area is undefined following a syntax error. 

Following a syntax error, the command string pointer is returned unchanged. 

Further Mnemonics 

Operands within a command may take the form of mnemonics, just as the verb did. These mnemonics are processed in the 
same way as the verb. Abbreviations may be used. The call to Mnemonic Table Scan is performed in the same way. 
Normally, a separate mnemonic table is used; however, it is possible to use the same mnemonic table that was used to find 
the verb. 

Notice that there is no provision in the call to Mnemonic Table Scan for the skipping of leading blanks. This means that the 
program has to perform this function, if it is desired. Also note that register PNTR must be pointing at the first character 
of the mnemonic to be scanned. This means that PNTR must be adjusted to skip the separator that followed the preceding 
verb or operand. 

ASCII Strings 

Even with all the facilities described previously, there are times when an operand does not quite fit any of the normal 
categories (Hexadecimal or Decimal numbers, File Descriptors, or mnemonics). OS/ 16 MT2 provides a call to meet these 
contingencies. This is the Move ASCII Characters call. This call should cover any special cases that cannot be handled by 
one of the normal calls. It has two options. One is used when a fixed number of characters must be moved from the com- 
mand string to a receiving area. This number of characters may not exceed 127. The format of the parameter block for 
this option is: 

MOVEF DB N,18,PNTR,OUTPTR 



The number of characters to be moved is indicated by N. PNTR is the current buffer pointer, as in all the preceding calls. 
OUTPTR is a register that holds a pointer to the location of the characters' placement. After the data is moved, OUTPTR 
is adjusted to point one byte beyond the last character moved. 

The second option is considerably more complex. This option is used when a variable number of characters, terminated by 
some separator, is to be moved. In this case, the parameter block is: 

MOVEV DB X'80'-HN,18,PNTR,OUTPTR 

DAC SEPSTR 
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The maximum number of characters to be moved is indicated by N. PNTR and OUTPTR are the current buffer pointer 
registers. SEPSTR is the address of a string of separators. When any of the separators in this string is found in the command 
string, the move operation is terminated. If none of the separators is found, the move operation terminates when the 
maximum number of characters (N) has been moved. The Condition Code V flag is set (CC=4) to show that no separator 
has been found. The separator string is coded as follows: 

SEPSTR DB NUM,SEP1,SEP2,SEP3,... 



where NUM is the number of separators in the string and SEPl, SEP2, etc., are the actual separators. For example, if the 
program wishes the move operation to terminate, if the character * or the character $ were found, the separator string 
appears as follows: 

SEPSTR DB 2,C'*$' 



A more possible example depicts the characters (blank), CR (carriage return), , (comma), or ; (semicolon) as valid 
separators. In this case, the separator string appears as: 



SEPSTR 


DB 


The calling method is as follows: 




LDAI 


OUTPTR,( 


SVC 
BO 


2,MOVEV 
NOSEPS 



4,C' ,;',X'OD' 



output buffer address to 

register OUTPTR 

move variable number of characters 

branch if no separator 

continue 
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CHAPTER 5 
GUIDE TO TASK- HANDLED TRAPS 



INTRODUCTION 

A complete OS/ 16 MT2 system encompasses a 16-Bit Processor, the OS/ 16 MT2 operating system, and a set of tasks. This 
section explores the makeup of a task at the task block structure level. A thorough discussion of the writing of the code 
contained in the executable task structures is beyond the scope of this section. For such information the reader is referred 
to: 

1 6-Bit Processor User's Manual 

Chapters 2 and 3 of this manual 

Common Assembly Language User's Manual 

The FORTRAN user should refer to the FORTRAN V Level II User's Manual for information on representing the various 
task structures described here in the FORTRAN language. 

This section also describes in detail the construction of task data structures using system STRUGS supplied with OS/ 16 
MT2. Examples are given for structures referred to in this section as well as general uses of system STRUCS. 

The various steps required to prepare a task for execution are also outlined. 



TASK STRUCTURE 

A task in OS/ 16 MT2 contains code to do the work of the task (Mainline Code), a set of User Dedicated Locations (UDL), 
and an initial Task Status Word (TSW). Any program, including a standard utility, that is to be run as a task under MT2, 
can be ignorant of its UDL and TSW since TET/16, which establishes it as a task; leaves the appropriate amount of space in 
its image output for the UDL and supplies an appropriate default for the initial TSW. 

In. addition to the UDL, TSW, and mainline code that a simple task might contain, the various features provided in MT2 
require additional task components. It should be understood that each additional component is only required to be 
included in the task if the MT2 facility it supports is to be used. The potential components of a task are as follows: 

Task Status Word (other than default) 

User Dedicated Locations 

Mainline Code 

Task Queue 

Task Queue Trap Service Routine 

Power Restoration Trap Service Routine 

The following discussions of each component indicate which OS facilities are involved and, therefore, which task 
components are to be included when writing the task during the task's design process. Figure 5-3, at the end of this section, 
summarizes which task components are required for various OS facilities. 

Task Status Word (TSW) 

The Task Status Word (TSW) describes the state of a task at any one time with respect to user controlled interaction with 
the operating system. The various task traps, as well as the different reasons for additions to the task's Task Queue are 
controlled through the task's TSW. This status word is used to enable or disable the various task traps, enable or disable 
additions to the Task Queue from various sources and contains the location counter and condition code upon taking and 
returning from task traps. TSW bit assignments are shown in Figure 5-1. 
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BYTE 



\vBITO 



15 



STATUS 



LOG 



TASK STATUS WORD IS 32-BITS. THE FIRST HALFWORD (BITS 0-15) CONTAINS 
STATUS DEFINED IN FIGURE 5-1. SECOND HALFWORD (BITS 16-31) CONTAINS 
THE CURRENT LOCATION COUNTER AS IN A PSW. 



STATUS BITS 


BIT 


HEX MASK 


NAME 


DESCRIPTION 





8000 


W 


TRAP WAIT - TASK SUSPENDED UNTI L A TASK TRAP OCCURS. 


1 


4000 


P 


POWER RESTORATION TRAP ENABLE - A TASK TRAP OCCURS 
ON COMPLETION OF SYSTEM POWER RESTORE SEQUENCE. 


2-3 






RESERVED - MUST BE ZERO. 


4 


0800 


Q 


TASK QUEUE SERVICE TRAP ENABLE - A TASK TRAP OCCURS 
WHEN AN ITEM IS ADDED TO THE TASK QUEUE. ALSO A TRAP 
OCCURS IF A TSW IS LOADED WITH THIS BIT SET AND THE 
TASK QUEUE IS NOT EMPTY. 


5 






RESERVED - MUST BE ZERO. 


6 


0200 


D 


ENABLE TASK QUEUE ENTRY ON INTERRUPT FROM A 
CONNECTED TRAP GENERATING DEVICE. 


7 


0100 


T 


ENABLE TASK QUEUE ENTRY ON QUEUE PARAMETER (SVC 6) 
REQUEST DIRECTED AT THIS TASK. 


8 


0080 


Z 


ENABLE TASK QUEUE ENTRY ON COMPLETION OF A TIME 
INTERVAL. 


9 


0040 





ENABLE TASK QUEUE ENTRY ON COMPLETION OF I/O 
PROCEED REQUEST. 


10 






RESERVED 


11 


0010 


E 


ENABLE TASK QUEUE ENTRY ON SEND MESSAGE 


12-15 


OOOF 


CC 


CONDITION CODE (AS IN PSW). 



Figure 5-1. Task Status Word (TSW) 
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The task has a current TSW at all times. The initial TSW of the task (the current TSW upon loading the task) is set at Task 
Establishment time. At that time a specific Initial TSW may be set; otherwise, the intial TSW defaults to zero (no traps or 
queue entries enabled), plus a location counter of the starting address specified at assembly time (argument of the END 
assembly statement) or, if unspecified, the start of the task code. 

When a task trap occurs (that is, when a trap causing condition occurs while the particular trap is enabled in the current 
TSW) the current TSW is saved in the appropriate area of the User Dedicated Locations (UDL) and a new TSW is loaded 
from the appropriate area of the UDL. The new TSW controls the traps or task queue entries that are to be allowed during 
the execution of the trap service routine. 

A task may change its current TSW at any time by executing an SVC 9 load TSW. The argument address of the SVC 9 call 
points to a four byte area aligned on a halfword boundary, containing the new TSW to be loaded. 

The first two bytes contain the status and the next two contain the location counter of the TSW. Following SVC 9 
processing, the task resumes execution at the location specified in the loaded TSW. If only the status of the current TSW is 
to be changed, without affecting the flow of execution of the task, a zero location counter should be specified in the new 
TSW. In this case, execution resumes at the instruction following the SVC 9 call. 

If an SVC 9 call loads a TSW enabling a task trap that is capable of occurring immediately (e.g., enabling Task Queue 
Service Trap while the Task Queue is not empty), a TSW swap occurs, storing the just loaded TSW in the UDL and loading 
a new TSW from the UDL. 

Also, an SVC 9 load of a TSW enabling Trap Wait places the task in Trap Wait, suspending execution until one of the traps 
enabled in the same TSW occurs. Since execution never resumes with the Trap Wait bit set, the location counter portion of 
such a TSW is ignored. 



NOTE 



If a task is in Trap Wait with no task traps enabled, it will wait 
indefinitely or until it is cancelled. 



User Dedicated Locations (UDL) 

A task's UDL starts at the first location within its partition. It contains Task Status Word (TSW) swap areas and other data 
used for communication between the operating system and the task, as follows (refer to Figure 5-2). Items in parentheses 
are the names of the relevant fields in the UDL STRUC, to be discussed later: 



CTOP (UDL.CTOP) 
COMBOT (UDL.CBOT) 

UTOP(UDL.UTOP) 

UBOT (UDL.UBOT) 

Power Restore Old TSW 
(UDL.PWRO) 

Power Restore New TSW 
(UDL.PWRN) 

Task Queue Service Old 
TSW (UDL.TSKO) 



Task Queue Service New 
TSW (UDL.TSKN) 

A (Task Queue) 
(UDL.TSKQ) 



A(Mcssage Buffer) 
(UDL.MSGR) 



Contains the program address of the highest halfword in the task's allocated memory. 

Contains same address as CTOP. Provided for compatibility with older 16-Bit Operating 
Systems. 

Contains the program address of the first halfword following the user's program. 

Contains the program address of the bottom of the user's program. 

Set by the operating system to the task's current TSW on occurrence of a Power Restoration 
Trap. 

Set by the user to the TSW to be loaded on the occurrence of a Power Restoration Trap. 
The LOC portion of this TSW points to a Power Restoration service routine. 

Set by the operating system to the task's current TSW on occurrence of a Task Queue 
Service Trap. A Task Queue Service trap occurs when task queue service trap is enabled in 
the current TSW and the Task Queue is non-empty. 

Set by the user to the TSW to be loaded on the occurrence of a Task Queue service trap. 
The LOC portion of this TSW contains the address of a Task Queue service routine. 

Set by the user to the address of the task's Task Queue. This location must be set prior to 
enabling any entries to the Task Queue. If the contents of this location is zero, no task 
queue entries are made regardless of the state of the Task Status Word's queue entry 
enabling bits (TSW.DIQM, TSW.TCM, TSW.IOM, TSW.TMCM). 

Set by the user to the address of the first (or only) message buffer, if messages are to be 
received from another task in the system. If this item is zero, no messages can be received. 
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USER DEDICATED LOCATIONS 



FIRST ADDRESS 
IN TASK 
PARTITION 



0(0) 
UDL.CTOP 


2(2) 
UDL.CBOT 


4(4) 
UDL.UTOP 


6(6) 
UDL.UBOT 


8(8) 

UDL.TSKQ 

• 


10(A) 

UDL.PWRO 


14(E) 

UDL.PWRN • 


"""^ 


18(12) 

UDL.TSKO 


22(16) 

UDL.TSKN •" 


^ 


26(1 A) 

UDL.MSGR 


28(10) 

RESERVED 


30{1E) 

RESERVED 


// 


36(24) 
SPFP 
REG 
SAVE 


68(44) 
DPFP 
REG 
SAVE 






/ TASK 




TASK MAINLINE 



START 

ADDRESS 



TASK QUEUE SERVICE HANDLER 



POWER RESTORE HANDLER 



STM Rx.TSKSAVE 
RTL Rx, TASKQ 



LM Rx.TSKSAVE 
SVC9,UDL.TSK0(RUDL) 



STM Rx, PWRSAVE 

• 

LM Rx, PWRSAVE 

SVC9,UDL.PWR0(RUDL) 



RUDL = pointer to task's UDL 



Figure 5-2. Task Structure 
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For the user supplied fields in the UDL (UDL.TSKQ, UDL.PWRN, UDL.TSKN, UDL.MSGR) there is a choice between 
assembling the UDL containing these fields as constants or loading these fields during the task initialization phase. After a 
program is assembled into object code, it must be established as a task with TET/16. 

If a task includes an assembled UDL, the command OPTION NOUDL must be passed to TET/16 at task establishment, so 
that TET/16 does not reserve a UDL area on behalf of the task. 

If a task sets up its UDL area dynamically at run-time, no special OPTION command is necessary. TET/16 automatically 
reserves and initializes the UDL to zero; 132 bytes if OPTION DFLOAT is specified, 68 bytes if OPTION FLOAT is 
specified, or 36 bytes if no floating point support is required. 

Mainline Code 

If the task is an autonomous program with no need of the task trap features of OS/16 MT2, the mainline code consists of 
the original program that is being run as a task. Together with its UDL, it is a complete task. 

However, when the task makes use of the task trap features of the OS, the exact function of the mainline code is a basic 
design choice. Mainline task code can be nothing more than a short start-up routine with all the work of the task being 
done in trap service routines or it can perform the bulk of the work with only small amounts of work done in the service 
routines. The particular design depends on the task's application. 

Task Queue 

Tlie operating system uses the Task Queue to inform a task of the occurrence of the events shown in Table 5-1. A Queue is 
used so that entries (referred to as items) resulting from events are not lost during the time the task is servicing a previous 
item. A Task Queue is formed by the assembly language statements: 

label DB n,0,0,0 
DSn*2 

Operand 'n' is the size (number of items capacity) of the queue, and label is used as the address of the Task Queue. 
UDL.TSKQ, in the UDL, must be set to this address before entries can be made to the Task Queue (see Figure 5-2). No 
specific advice is given for the size of the queue since this decision depends on the task's application and expected 
frequency of occurrence of queue-related events compared to the individual event service time. In general, if a queue re- 
lated event occurs when the queue is full, the associated item is lost. Therefore, the following guidelines should be used in 
determining a minimum queue size: 

1 entry for each device capable of interrupting concurrently 
n entries for each task capable of queueing n parameters concurrently 
1 entry for each Logical Unit having concurrent I/O proceeds 
1 entry if a time interval trap is to be scheduled (SVC 2 code 23) 
m entries for each task capable of sending m messages concurrently 

A Task Queue Service Trap occurs whenever the Task Queue Service Trap enable bit (Bit 4, symbol: TSW.TSKM) is set in 
the current TSW and the Task Queue is non-empty (i.e., has at least one item in it). Items are added to the queue only if 
the particular queue entry enabling bit is set in the current TSW (shown in Table 5-1). 

The Task Queue is a standard INTERDATA 16-Bit Series circular list (refer to the 16-Bit Processor User's Manual, Chapter 
3, for a detailed description). The operating system adds items to the bottom of the queue, therefore, the task would 
typically remove items for servicing from the top of the queue. For example: 

RTLR1,TASKQ 

(an item is removed from the top of the Task Queue at TASKQ and placed in register Rl for examination/processing). 

The user can use the ABL machine instruction to add simulated items to the queue before enabling Task Queue Service 
Traps, thereby simulafing a Task Queue Service Trap, perhaps to start off a cycle of I/O Proceeds. 

Resident Tasks that are to be cancelled and restarted by other tasks should initialize their Task Queues to an empty state 
each time they are restarted to prevent old queue items from causing erroneous behavior by the task. An example of code 
to initiaUze a Task Queue at address TASKQ is: 

LIS RF,0 

STB RF,TASKQ+1 

STH RF,TASK0+2 
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TABLE 5-1 . TASK QUEUE ITEMS 



SOURCE 



Device Interrupt 



SVC 6 Queue 
Parameter 

Timer 
Termination 

I/O Proceed 
Completion 

Task message 
Received 



QUEUE ENTRY ENABLING BIT* 



X'0200 
(TSW.DIQM1« 

x'oioo' 

(TSW.TCM) * 

X'OOBO' 

(TSW.TMCM)' 

X'OO40' 
(TSW.IOM)« 

x'ooio' 

(TSW.PMM) * 



CONTENTS OF ITEM 



Parameter associated 
with device 

Parameter specified 
in call 

Parameter specified 
in call 

Address of SVC 1 
Parameter Block 

Address of message 
buffer 



* The name in parentheses is the symbolic name of the mask used to enable the associated bit (to be discussed later). 



Task Trap Service Routines 

A Task Trap occurs when a particular Task Trap is enabled in the current TSW at the time of a trap causing event. Table 
5-2 gives the types of Task Traps, enabling bit in the current TSW, and Trap Causing event. 

TABLE 5-2. TASK TRAPS 



TASK TRAP 


ENABLING BIT* 


EVENT 


Power Restoration 
Task Queue Service 


X'4000' 
(TSW.PWRM) * 

X'OBOO' 

(TSW.TSKM)* 


System Power Restoration 
Task Queue Non-Empty 



* The name in parentheses is the symbolic name of the mask used to enable the associated bit. 



A trap service routine must be written and included in the task for each task trap to be used. Prior to enabling the Task 
Trap, the TSW swap area in the UDL for that trap must contain a new TSW for that trap (see Figure 5-2). The status 
portion of the new TSW is the Task Status to be in effect during the execution of the trap service routine; the location 
counter portion is the entry address of the trap service routine. Care must be exercised in enabling any Task Traps in the 
new TSW status of a particular Task Trap. (If two Trap Service routines, A and B, enabled each other's Trap and Trap A 
occurred. Trap B might occur enabling Trap A again and if Trap A occurs, the first old TSW for Trap A would be lost.) 

Since a Task Trap may occur during execution of code elsewhere in the task it is the responsibility of each Task Trap 
service routine to save any registers it uses to avoid disturbing the interrupted code. 



Task Queue Service Routine 

This user written routine is entered upon a Task Queue Service Trap (i.e. , whenever Task Queue service is enabled in the 
current TSW and the Task Queue is non-empty). The Task Queue Service new TSW field of the UDL (that is, the TSW in 
effect during Queue Service) typically has a status disabling Task Queue Service (if enabled, the Task Queue Service routine 
could interrupt and reenter itself with dubious consequences) but enabling various queue entries to continue while the 
trap-causing item is serviced. 
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Table 5-1 shows the five types of events that can cause items to be added to the taslc queue. Each item is 2 bytes in length 
with the content dependent on the particular item as follows: 

Device Interrupt: The item is the parameter specified at the time the Trap-Generating Device was CONNECTed (via SVC 6) 
to the Task. 

SVC 6 Queue Parameter; The item is the parameter specified in SVC 6 parameter block causing a parameter to be queued 
to this task. 

I/O Proceed Completion: The address of the SVC 1 parameter block of a completed I/O proceed. 

Interval Completion Termination: The item is the parameter specified in the SVC 2 code 23 which caused the Timer 
Termination. 

Task Message Received; The item is the address of the message buffer. 

The item is removed from the Task Queue with an RTL instruction. After the trap-causing item is decoded and the 
appropriate action taken, the Task Queue Service routine typically exits with an: 

SVC 9,UDL.TSKO(RUDL) 

where UDL.TSKO is the symbolic name of the UDL Task Queue Service old TSW save area (to be discussed later) and 
RUDL is a pointer to the task's UDL. By loading the old TSW in this way, execution resumes at the location, with the 
status in effect, at the time the task was trapped. If additional items are on the Task Queue, loading the old TSW causes the 
Task Queue Service trap to recur for service of the additional items. 

Power Restoration Trap Service Routine 

This user written routine is entered upon a Power Restoration Trap (whenever Power Restoration trap is enabled in the 
current TSW and a system power restoration takes place; note that if the Power Restoration Trap is disabled at the time of 
a system power restoration, the task is PAUSEd. Once this routine is entered, it can go about the business of recovering the 
task from the power outage (highly application dependent), and if it determines the situation warrants resumption of the 
task, the routine exits with: 

SVC 9,UDL.PWR0(RUDL) 

Figure 5-3 summarizes task requirements. 
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Figure 5-3. Task Requirements Summary 
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OS/16 MT2 SYMBOLS AND STRUGS 

The CAL Assembler provides a powerful facility for referencing, by name, numerical constants and constant displacements 
within a data structure (STRUCs) (refer to the Common Assembler Language User's Manual, for detailed syntactical 
description of STRUCs). A reference made in such a way is said to refer symbolically to a constant (or constant dis- 
placement). 

Symbolic references are generally much easier to use than their numeric counterparts because of the ease in remembering a 
name. Errors involving references are less likely since using an inaccurate numerical constant is usually assembled without 
an error while using an inaccurate symbolic name is caught by the assembler (as an undefined symbol). Symbolic references 
help make assembly language code easier to read and understand because symbolic names can be chosen to reflect the 
meaning of the numerical constant represented or the name of the field within a data structure which the symbol points to. 
Lastly, in the event that a numerical constant or displacement is ever changed, code using symbolic references is easier to 
update since the update necessitates changing only the symbol definition rather than every reference (as would be needed 
with numerical references). 

Numerical constant symbols and displacement symbols (STRUCs) are used throughout the coding of OS/ 16 MT2 and these 
same symbols and STRUCs are equally usable by assembly language programmers writing programs to run under MT2. The 
collection of symbols and STRUCs related to OS/ 16 MT2 is contained in the Parameters and Control Blocks module 
supplied with the system source (filename PCB16.CAL for MT on disc). Some examples of uses by user tasks follow: 



1. Construction of a Task Status Word: 

The status portion of a Task Status Word (TSW) enabling Trap wait. Task Queue service trap. Queue 
entry on Task call (queue parameter from another task) and I/O proceed termination can be written: 



COPY 



UDL 



DC 



TSW.WTM!TSW.TSKM!TSW.TCM!TSW.IOM 



This expression instructs the assembler to OR together masks, each setting a particular bit, to form a 
word with all the required bits set. (Within the Parameters and Control Blocks module symbol 
definitions, symbols ending in 'M' have the value of the bit mask needed to enable a particular bit.) 

2. Loading a TSW into the User Dedicated Locations (UDL): 

A TSW enabling queue entry on I/O proceed termination and timeout completion is to be loaded into 
the "Task Queue service new TSW" field of the User Dedicated Locations, thereby allowing queue 
entries for these two events to continue while the Task Queue is being serviced. The TSW in question 
contains a LOC field pointing to the Task Queue service routine. 



COPY 



UDL 





SVC 

LM 
STM 


2,FETCH 

R14,TSKQTSW 

R14,UDL.TSKN(R13) 


QSERVICE 


EQU 


* 


FETCH 
TSKQTSW 


DB 
DC 
DAC 


0,2 
13 
TSW.IOMITSW.TMCM 



GET ADDRESS OF UDL INTO R13 
LOAD TSW INTO REGS 14-15 
STORE INTO UDL 



TASK QUEUE SERVICE ROUTINE 



Note that the one line definition of the TSW (TSKQTSW) generates two halfwords: a STATUS 
portion enabling certain bits and a LOC portion pointing to the task queue service routine as 
QSERVICE. 
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3. Loading an SVC 6 function code into an SVC,6 parameter bloclc: 

A function code specifying Load and Start immediately for some "othier" taslc, (as opposed to a 
self-directed SVC 6) is loaded into an SVC 6 parameter block. 



COPY 



SVC6. 



LHI R14,SFCl.DOM!SFCl.LM 

LHI R15,SFC2.SIM 

STM R14,PARBLK+SVC6.FUN 



LOAD FUNCTION 
START FUNCTION 
STORE INTO SVC 6 P.B. 



PARBLK 



EQU 
DS 



SVC 6 PARAMETER BLOCK 



SVC6. 



Note that the proper amount of space for the SVC 6 parameter block was reserved by a "DS SVC6." 
where "SVC6." is the label of the STRUC defining the SVC 6 parameter block and set by CAL to the 
size of the data structure so defined. 

A field within a data structure can be referenced in one of two ways using a STRUC: 



COPY SVC6. 



STM R14,PARBLK+SVC6.FUN 



DS SVC6. 

or referencing a field through an index register: 
COPY SVC6. 



LDAI R3, PARBLK 



STM R14,SVC6.FUN(R3) 



PARBLK DS 



SVC6. 



The direct method has the advantage of not using an additional register while the index register 
method has the additional flexibility of passing the address of different parameter blocks through a 
register (perhaps to a subroutine). 

The previous examples deal with applications where a program dynamically loaded various fields with 
appropriate values. This approach is correct for occasions where the contents of the various fields 
change with time and therefore, must be dynamically initialized and subsequently changed. However, 
for applications where the contents of fields remain the same for the duration of the task, it saves both 
assembly code size and execution time to assemble the appropriate values into the data structures. 
Some examples follow. 
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Assembling values into a UDL (assembling a UDL as part of a task requires an OPTION NOUDL 
statement in the TET/16 input at task establishment time): 



TUDL 



COPY 


UDL 


EQU 


* 


ORG 


TUDL+UDL.TSKQ 


DC 


task queue addr 


ORG 


TUDL+UDL.PWRN 


DC 


status.loc 


ORG 


TUDL+UDL.TSKN 


DC 


status ,loc 


ORG 


TUDL+UDL 



ADDRESS OF TASK QUEUE 
POWER RESTORE NEW TSW 
TASK QUEUE SERV NEW TSW 



Note that the label 'TUDL' is used so as not to conflict with 'UDL' which is defined in the UDL 
STRUC (invoked by the COPY UDL). To omit any of the above field definitions from the code simply 
delete the ORG to the relevent field plus the constant definition for that field. The 'ORG 
TUDL+UDL' sets the location counter past the end of the UDL. 

5. Assembling Task ID and function code into an SVC 6 parameter block at PARBLK: 
COPY SVC6. 



PARBLK 


EQU 


* 




ORG 


PARBLK+SVC6.ID 




DC 


C'TASKA 




ORG 


PARBLK+SVC6.FUN 




DC 


SFCl.DOM,SFC2.SIM 




ORG 


PARBLK+SVC6. 



TARGET TASKID 

START IMMED.FUNCTION 



NOTE 

The ORG PARBLK+SVC6. sets the location counter past the 
end of the Parameter block. 

STRUCs are provided for SVC 1, SVC 5, SVC 6, and SVC 7 parameter blocks, and the User Dedicated Locations. They can 
be used after a CAL 'COPY' of the relevant name (a COPY statement instructs CAL to include source from Logical Unit 7, 
in this case the Parameters and Control Blocks module): 



STRUC 


COPY 


SVCl 


SVCl. 


SVC 5 


SVC5. 


SVC 6 


SVC6. 


SVC 7 


SVC7. 


UDL and TSW Bits 


UDL 



Refer to Appendix 3 for assembly listings of the complete Parameters and Control Block module. 



NOTE 



Certain fields and bits in the UDL, TSW and SVC 6 STRUCs are 
included for future extensions of the Operating System and should 
be ignored by users of ROO and ROl OS/ 16 MT2. 
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TASK PREPARATION 

A task must go through various transitions between the time it is written by the programmer in assembl^y language (or a 
combination of FORTRAN and assembly language or FORTRAN alone) and the time it is run under OS/ 16 MT2. These 
steps include the following (refer to Figures 5-4, 5-5, and 5-6): 

FORTRAN Compiler - if required, this compiles the FORTRAN source plus any imbedded assembly language into CAL 
source (see the FORTRAN V Level 1 Reference Manual, FORTRAN V Level 1 User's Guide, and 
FORTRAN V Level 1 Run Time Library Manual for details). 

CAL Assembler - This translates the CAL assembly language into 16-Bit object format output (see the Common Assembler 
Language User's Manual). 

TET/16 - This converts the object format output of CAL into memory-image format. References by the TASK to a 
resident library partition are resolved with TET RESOLVE command (Figures 5-4 and 5-6). Relevant 
routines from the library can be included in the task itself with a TET EDIT command (Figure 5-5). (See 
the OS/16 MT2 Operator's Manual, Chapter 5, for a complete discussion of TET with additional examples.) 

OS/ 16 MT2 - The OS/ 16 MT2 loader loads the task or library (via operator command or SVC 6) that was established by 
TET, and allows it to run on a 1 6-Bit Processor. 



NOTE 

For a task to use TASK COMMON, it must contain a labelled 
Common with the Label TSKCOM' at assembly time (the 
left-hand CAL box in Figure 5-4). All program references to this 
common block are resolved by TET/16 to a reference into user 
specified TASK common partition. 



CAL 
SOURCE 



LIBRARY 
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Figure 5-4. CAL Source 
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FORTRAN 
SOURCE 



RELEVANT RTL ROUTINES WITHIN THE TASK 
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Figure 5-5. FORTRAN Source 
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Figure 5-6. FORTRAN Source With RTL 
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CHAPTER 6 
GUIDE TO OS/16 MT2 FILE STRUCTURES 



DEFINITION OF TERMS 

Certain terms, which are used in this section, must be defined in order to gain a good understanding of the concepts to be 
presented later. These definitions should be read by even the advanced reader, since the same terms have been used 
throughout the data-processing industry with unfortunate, inconsistent meanings. Refer to Appendix 9 of the System 
Planning and Configuration Guide for definitions. 

FILE IDENTIFICATION 

The OS/16 MT2 file is identified by a File Descriptor. The full name of a file has three parts: volume name, filename, and 
extension. The volume name is composed of one to four alphanumeric characters, of which the first character must be 
alphabetic. This is the name of the volume on which the file resides. 

The filename consists of one to eight alphanumeric characters, of which the first must be alphabetic. This is the main 
identifier for the file, and may be anything the user chooses, 

Tlie extension consists of up to three alphanumeric characters. It may consist of no characters at all, in which case it is 
considered to be made of blanks. The extension usually denotes the type of material on the fife. It may be anything the 
user chooses, however; some specific extensions are used by OS/16 and by some OS utilities, and are assumed to have 
specific meanmgs. These extensions are: 



TSK Task Image format 

OBJ Absolute or Relocatable loader format 

FTN FORTRAN source format 

CAL CAL assemblv language source format 

BAS BASIC source format 

ROL Roll file for Roll In/Out 

CSS Command Substitution System source format 

MAC CAL Macro source format 

Other extensions may be defined from time ,to time as required. The user may use any of these standard extensions, or may 
define others. 

File Descriptors are written as follows: 

VOLN:FILENAME.EXT 

where VOLN is the volume name FILENAME is the filename, and EXT is the extension. VOLN is often omitted in writing 
and in OS commands. EXT is sometimes omitted, in cases where the extension is already known. 

Some examples of valid File Descriptors are : 

FRED:PROGRAM.CAL A program named PROGRAM, in CAL source format, on volume FRED. 

FRED:PROGRAM.OBJ The same program, in loader format. 

FRED:PROGRAM.TSK The same program in task image format. 

GOLF: BOGEY. XYZ The volume now is GOLF; the extension XYZ is not standard, so no assumptions can be 

made about format. 

FLAH:BOGEY.XYZ The same file on a different volume. Although all filename/extension combinations on 

any one volume must be unique, the same filename/extension may exist on more than 
one volume. 
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LULU. 

V0L3: DATABASE 



The volume name is omitted and should be identifiable in the proper context. The 
extension field is blank. 

The extension is omitted here. This may not be the same as the blank extension, but the 
true extension should be identifiable from context. 



Note that when the volume is specified, a colon (:) is always present. When the extension is specified, a period (.) is always 
present. 



Some invalid File Descriptors are: 

2V:ABC.CAL 
V3:FILE #2.0BJ 
SYSVOL:FILE.DMP 
SV:.EXT 
PROGRAMS 25 



Volume name begins with a numeric 
File name contains a non-alphanumeric 
Volume name too long 
File name nonexistent 
File name too long 



A file is originally named when it is allocated. At this time the specified name is checked to see if it is unique on the given 
volume. A file can be renamed at a later time, either by the console operator or by a user program. At this time, the new 
name is checked to make sure it, too, is unique. 

The renaming function can be used, for example, to handle the updating of a file, when it is desired to retain the older 
version of the file. One way to do this might be: 

(Assume the file to be updated is named FILE.XYZ) 

1. Rename FILE.XYZ to be FILE.BAK 

2. Allocate a new file named FILE.XYZ 

3. Copy FILE.BAK onto file FILE.XYZ, adding update information as required. 

Now there is a most-recent version named FILE.XYZ, and a next-most-recent version named FILE.BAK. When the backup 
is no longer needed, FILE.BAK may be deleted from the volume. 



FILE PROTECTION 



Files may be protected in one of two ways: statically or dynamically. 



Static Protection 

Each file has two protection keys, one for Read access and one for Write access. These keys are first set up when the file is 
allocated. Each key is one byte long and may have any value. 

If the values of the keys are within the range X'Ol' to X'FE', the file may not be assigned for Read or Write access unless 
the assigning task matches the appropriate keys. In other words, if a file's Read key is X'3A' and its Write key is X'57', a 
task trying to assign the file for Read access must supply a Read key of X'3A'. To assign this file for Write access, a Write 
key of X'57' must be supplied. In order to assign the file for both Read and Write access, the task must supply both keys. 

The values X'OO' and X'FF' have special meanings. If a key has a value of X'OO', the file is unprotected for that access 
mode. Any key supplied by the assigning task is accepted as valid. If both keys have a value of X'OO , tlierefore, any 
attempt to assign the file is accepted, regardless of the keys supplied by the assigning task. 

If a key has a value of X'FF', the file is unconditionally protected for that access mode. It may not be assigned for that 
access mode by any task, regardless of the key supplied by the assignment task. However, an E-task (an executive task, 
with the same privileges as the operating system itself) may assign any file, even if its protection keys are set to X'FF'. 
Static protection does not apply to E-tasks. 



Some examples of Static protection are: 



Write 


Read 


Key 


Key 


00 


00 


FF 


FF 


07 


00 


FF 


A7 


00 


FF 


27 


32 



Meaning 

Completely unprotected. 

Unconditionally protected. 

Unprotected for Read, conditionally protected for 

Write (user must supply Write key = X'07'). 
Unconditionally protected for Write, conditionally 

protected for Read. 
Unprotected for Write, unconditionally protected 

for Read. 
Conditionally protected for both Read and Write. 
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Dynamic Protection 

While a task is using a file, it may wisti to prevent other taslcs from accessing that file. An example might be a task that is 
updating a shared data base. In most cases, it would not be appropriate to let the data base be read while the updating 
operation is under way. For this reason, the task may ask for exclusive access privileges, either for Read or Write, when it 
assigns a file. If it is granted exclusive access, it may be sure that the file is not accessible by any other task until it is 
closed, or until the task voluntarily gives up exclusive access. This form of protection is called dynamic because it is only in 
effect while the file is actually assigned. 

The access privileges are generally known by their abbreviations: 



SRO 

ERO 

SWO 

EWO 

SRW 

SREW 

ERSW 

ERW 



Shared Read-only 
Exclusive Read-only 
Shared Write-only 
Exclusive Write-only 
Shared Read-Write 
Shared Read, Exclusive Write 
Exclusive Read, Shared Write 
Exclusive Read-Write 



Protection Modification 

The protection keys of a file may be changed by the console operator, or by any task having that file assigned for Exclusive 
Read-Write (ERW). 

A task may change its access privileges on a file without having to close the file. This is only possible if the proper 
conditions are met. A task having a file assigned for shared Read, for example, may not change to exclusive Read if the file 
is also assigned for shared Read to another task (or another Logical Unit of the same task). Access may always be changed 
from exclusive to shared, however. 

If the user attempts to change access privileges, and for some reason is unable to get the new privileges, the old access 
privileges remain. 

Multiple LU Considerations 

The concept of exclusive access has been discussed in terms of multiple tasks sharing the same file. Here it was assumed 
that a single task does not attempt to assign the same file to multiple Logical Units (LU). Occasionally, however, a case 
arises when the task does desire to assign the same file to multiple LUs. This might occur as a result of default assignments 
or assignments made by the console operator. In this case, exclusivity applies between LUs just as between tasks. This 
means that a file connot be assigned for exclusive Read access on one LU and shared Read on another. If a file is assigned 
for exclusive Read or Write access on any given LU, it may not be assigned for that kind of access on any other LU. 

Assume that a file is open on LU 1 and LU 2 at the same time. The following matrix shows the compatible combinations: 



LU 2 




SREW 



EWO 



SWO 



SRW 



SRO 



ERO 



ERSW 



ERW 



SREW 

EWO 

SWO 

SRW 

SRO 

ERO 

ERSW 

ERW 



■ compatible 
incompatible 
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ACCESS METHODS 

08/16 supports two methods of access to files: random and sequential. These methods may be intermixed without having 
to close and reassign the file. The chief mechanism used to implement these methods is the current record pomter. 

The current record pointer is a number, ranging from zero to the number of records currently in the file, indicating the 
record to be read or written on the next sequential access to the file. Each record is numbered in sequence, starting with 
ZERO. 

The current record pointer may be adjusted in one of several ways: 

1 . It is set to ZERO by the following operations: 

Rewind 

Backspace to filemark (except on configuous files) 

Assigning (except for Write-Only access) 

2. It is set to the number of records in the file (the proper position to append new records) by the 
following operations: 

Assigning for Write-Only access 

Forward to filemark (except on Contiguous files) 

3. It is decremented by one by a backspace record operation, unless the file is already positioned at its 
beginning. 

4. It is incremented by one as follows: 

Forward record (unless already at end of file) 
Sequential Read or Write 

5. A random Read or Write sets the current record pointer to a value one greater than the record read or 
written. 

Use of the Unbuffered Physical buffer management method causes the current record pointer to be reinterpreted to a 
certain extent. This is discussed fully, later. 

Random Access 

For random access, the user supplies the record number to Read or Write. This record is found, data transfer is performed, 
and the current record pointer is set to point to the next sequential record. If the user continues to use random access, 
there is no need to pay attention to the current record pointer, since it is readjusted on every call. However, the user may 
wish to read or write a sequence of records, starting with a known record number. In this case, one would use a single 
random call and follow with a number of sequential calls. 

On Indexed files the user is somewhat restricted in the use of the random Write call. This call may be used to update any 
record currently in the file, or to append one record to the end of the file. If the record number specified is more than one 
record past the end of the file, the call is rejected with EOF (end of file) status. Effectively, this means that a file must be 
expanded sequentially. If the file has only five records, a sixth may be added but record number 100, for example, cannot. 
Otherwise, the system would have to create a large number of null, or vacant, records between the old end of the file and 
the new record. For reasons of safety and time considerations, OS/ 1 6 does not do this. 

On Configuous files there is no restriction on the use of the random Write or Read call. Any record within the file's 
allocation may be read or written. 

Sequential Access 

Sequenfial access is the simplest and most common access method. The user performs a series of sequenfial Read or Write 
calls. These cause records of the file to be read or written in sequence. The current record pointer is adjusted automatically 
at each access. The REWIND, FORWARD RECORD, BACKWARD RECORD, FORWARD FILE, and BACKWARD FILE 
commands may be used for repositioning as described previously. 



BUFFER MANAGEMENT 

OS/ 16 MT2 supports two buffer management methods: Buffered Logical (BL) and Unbuffered Physical (UP). One of these 
buffer management methods is specified each time a file is assigned. From that time until the file is next closed, the buffer 
management method may not be changed. The buffer management method is logically independent of file structure, access 
method, or the contents of the file. 
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Buffered Logical 

In the Buffered Logical (BL) method, files are divided into logical records. These logical records may be of any length, 
regardless of the physical block size of the file. The logical record length for any given file is fixed at the time it is 
allocated. Thereafter, it is a permanent attribute of that file. It would be impossible therefore to write twenty-byte records 
on a file one day, and then the next day to write eighty-byte records on the same file without resorting to subterfuges. 

It is possible to read or write less than a logical record; however, this can waste space, since the file is divided physically 
into logical records of the size specified at the time the file was allocated. Likewise, it is not possible to write 
variable-length records on a file without wasting space. In such a case, the logical record length specified at allocation time 
must be the size of the longest record ever to be written on that file. If the user tries to read or write a record that is longer 
than the file's logical record length, data is lost on a write operation, and is not returned on a read operation. 

The BL buffer management method packs logical records into physical blocks as efficiently as possible, allowing logical 
records to overlap into the next physical block if necessary. For example, if the amount of space in a physical block that is 
available for data storage is 256 bytes (a common figure on an Indexed file), and the logical record length is 80 bytes, 
sixteen logical records are packed into five physical blocks. The logical record size may exceed the size of a physical block. 
The only restriction on logical record size is that no logical record may exceed 65,535 bytes. 

All logical to physical transformations are handled automatically by the BL buffer management method. When a block is 
read or written, the actual data transfer takes place between the device and a buffer in system space. This buffer is not 
accessible to the user program. When a task reads or writes a record, data is transferred between the task and the system 
buffer. Actual reads and writes take place only when required. All actions of the buffer management method are fully 
transparent to the user. 

The BL buffer management method is probably the most convenient for general-purpose use. For sequential access, it is 
highly efficient, and it makes good use of disc space. Its primary drawback lies in the area of random Writes. In order to 
update a record, the physical block that the record lies in must be read first, to keep from destroying data in records that 
are in the same block but not being updated. Therefore, a random updating process may require a number of disc accesses 
that is far out of proportion to the number of records being updated. 

Unbuffered Physical 

Tlie Unbuffered Physical (UP) management method does not operate on logical records, but works directly on physical 
blocks. Data is transferred directly from a buffer in the user program to the device, without being moved into a system 
buffer. For a Write operation, data is moved directly from the device to the user program. 

The current record pointer is reinterpreted in the UP method. In this buffer management method, the current record 
pointer points to the current physical block. Otherwise, it is the same as in the BL method. All data transfers must begin 
on a physical block boundary. The length of data to be transferred may be less than the size of a physical block. Tlie 
Contiguous file structure permits data transfers larger than a physical block, of any size up to the total size of the file. In 
this file structure, therefore, the current record pointer may be incremented by more than one following a data transfer. 

Tlie advantages of the UP method lie in the speed with which data transfers can be done. There is no time required for 
moving data in core between system and user space if this method is used. Its primary disadvantage is that space on the 
volume is often wasted when using this method. 

FILE STRUCTURES 

OS/16 MT2 supports two file structures. Although these structures differ, in most cases the same data manipulations can 
be performed on one structure as another. The user's choice of file structure does not usually depend on the kind of data 
to be put in the file, but on the way the data is to be accessed. OS/ 16 file structures are each optimized for one specified 
form of access. 

OS/ 16 file structures may be broadly divided into two categories: open-ended and closed. An open-ended structure may 
expand dynamically as new data is added. The maximum size of an open-ended file is limited only by the amount of space 
available on its volume. When an open-ended file is allocated, no space is reserved for it on the volume; space is only seized 
as it is required. The Indexed file structure is open-ended. 

A closed structure is limited in size at the time it is allocated. Space is reserved for it at that time. Thereafter, it may 
neither expand nor contract. The Contiguous file structure is closed. 
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The advantages of open-ended structures are many. First, the user need not worry about the maximum size of the file. 
(Tliis parameter is often difficult or impossible to compute.) Second, unused space on the volume is not wasted, but is 
available for use by other files. This tends to permit a greater number of files per volume. In most cases, the user 
programmer should choose an open-ended file structure. 

The primary advantage of closed structures lies in the fact that all the space required for the file is reserved at allocation 
time. If the maximum length of the file is known, the user may be sure that there is always room for the data and that no 
other tasks have preempted needed disc space. This advantage comes at the cost of wasted space on the volume. 

At this time, not all access methods and buffer management methods are supported on all file structures. 

Indexed Files 

The only open-ended file structure in OS/ 16 MT2 is the Indexed file. The Indexed structure consists of a chain 
of index blocks (see Figure 6-1). The first two fuUwords of each index block are used as links. The first fullword points to 
the previous block (it is zero in the first block). The second fullword points to the next block (it is zero in the last block). 
The rest of the index block contains fullword pointers to the data blocks which are the physical records of the file. Two 
fullword pointers in the volume directory point to the first and last index blocks. 

At allocation time, two physical block sizes may be specified. They are the index block size and the data block size. 
Normally, these block sizes are one sector each (256 bytes), but any number of sectors may be specified. The index block 
size determines the number of data pointers to be contained in one index block. The data block size determines the 
amount of data space available in one data block. 256 bytes of data are contained in a one sector data block. 
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Figure 6-1. Indexed File Structure 
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Contiguous Files 

The Contisuous file structure (see Figure 6-2) is a closed-ended file structure supported by OS/ 16 As the name implies, all 
biocks 3 a ContSuous flk a^ contiguously on the volume. The file size is specified at the time of allocation, and 

ai required space is reserved at that time. This gives the Contiguous file certain characteristics that are unique to this file 
structure. 




DIRECTORY 



Figure 6-2. Contiguous File Structure 



Random Reads and Writes may access any record or block on the file, regardless of which records have been previously 
written Till makes it possible to create a Contiguous file in a truly random fashion. (At the same time, it should be noted 
Tat it is possible to read a record or block that has never been written. In such cases, the data returned is not defined.) 

The Contiguous file supports a pseudo-filemark capabiUty that gives it some of the characterisfics of a magnetic tape 
device TTie filemark is X'l313' at the beginning of a record or block. Care should be taken to ensure that this datum is not 
fnadvertenfiy written at the beginning of a record or block. The forward-file and backward-file operations on a Contiguous 
file work as they would on a magnetic tape. That is, the file is positioned forward or backward respectively until a 
"filemark" L found. TTie current record pointer is then left following or preceding this filemark, "■^^P^'^fvely Note tha 
this removes the capability of setting the file up for an append operation by usmg the forward-file command (It may still 
be set up for append by initially opening it for Write-Only). The Write-filemark operation is implemented on this file type, 
and results in the writing of the X'1313' mentioned previously. 

It is permissible to read or to write data longer than the physical block length of a Contiguous "l^- ^he physi^cal bl^ock 
length of a Contiguous file is always one sector, or 256 bytes. The current record pointer is adjusted to point to the next 
block following the data transfer, in this case. 

Use of the Contiguous file provides the fastest possible means of access to Direct-Access storage. If time is of the essence 
this structure should be used. However, it wastes space, is not open-ended, and requires a number «[, '^^f t'S^^^f 7^';='"* 
sectors on the volume in order to allocate such a file. A Contiguous file, therefore, may be impossible to allocate on a 
heavily-used checker-boarded disc. 

FILE MANAGEMENT 

This section discusses the use of the Allocate, Assign, Close, Delete and Checkpoint calls. The Rename and Reprotect calls 
have been discussed as has the Change Access Privileges call. 

Allocation 

When a file is allocated, its directory entry is built and, if it is a Contiguous file, space is reserved for it on the disc. The 
allocation of a file does not cause the file to be assigned; this is done by the Assign call. A file may be allocated either from 
the system console or from a user program. Regardless of how a file is allocated, however, certain information must be 
specified: 

Volume ID: This specifies the volume on which the file is to be allocated. It must be the name of im on-line 

\ Direct- Access volume; otherwise, "volume error" is returned. 



Filename/extension : 

Write key/Read key: 
Logical record length: 

Size: 



This gives the newly allocated file its name. There must not be any other file of that name and 
extension on the specified volume; otherwise, "name error" is returned. 

This sets up the initial protection keys for the file. 

This sets the logical record length for the file. It may be any size up to 65,535 bytes; however, 
it may not be changed. If the logical record length is set to ZERO, the BL management 
method may never be used with this file. 

For a Contiguous file, this is the size of the entire file, in sectors. May be any size up to the 
maximum amount of contiguous space available on that volume at that time. If too large, size 
error" is returned. 

For an Indexed file, this field is broken up into two halfwords. The first halfword is the index 
block size, the second halfword is the data block size. These block sizes are specified as a 
number of sectors (never greater than 255). If the index block size is specified as ZERO, an 
index block size of ONE is used. 



File type: 



Indexed or Contiguous. 
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Assignment 

To assign a file to a Logical Unit, the Assign call (SVC 7) is used from a user program, or the ASSIGN command from the 
system console. At this point, the desired access privileges and buffer management method must be specified. The Read 
key must be given, if Read access is requested; the Write key must be specified for Write access. 

At the time of assignment, the system allocates, out of system space, a File Control Block (FCB) and buffers for the file. 
The buffer space required, if any, depends on the chosen buffer management method and on the file's physical block size. 
If the physical block size of the file is too great for the amount of remaining system space, the file may not be assigned. In 
this case, a buffer error status is returned; the user program may attempt to relinquish some memory and then retry the 
assignment. If that does not work, the user has little choice but to complain to the console operator and abort the task. Of 
course, if the user has another file assigned that can be closed, that can be done to release space to the system. 

For this reason, the user should not keep files assigned longer than necessary. In addition, the physical block length of files 
should be kept as short as possible unless there are overriding considerations. 

Oosing 

A file may be closed at any time by issuing a Close call. No information other than Logical Unit need be specified. The 
system waits for any incomplete data transfers to terminate, flushes the buffers (that is, writes out to the volume any 
partly filled buffers), and updates the file's directory entry. The Logical Unit that the file was assigned to is deassigned. 

Deletion 

A file may be deleted only if it is not currently assigned to any task. Tlie user must supply the volume name, file name and 
extension, and both Read and Write keys. When a file is deleted, all its space on the volume is released and may be used by 
the files. 

Checkpointing 

The Checkpoint call performs the buffer-flushing and directory-updating functions of a Close call, without performing any 
of the other functions of a Qose operation. This is essentially a protective operation that can be used to guard against 
system failure, either for very critical files, or for files assigned for lengthy periods of time without being closed. 

Since the directory is only updated at close or checkpoint time, data appended to a file after the latest close or checkpoint 
operation is lost at system failure for certain types of files and buffer management methods. When a file is closed or 
checkpointed, however, all data appended prior to that time is guaranteed safe through a system failure, providing that the 
system failure did not destroy the volume directory. 

The checkpoint operation is never required for Contiguous files, since data is written directly to the disc, and this file 
structure does not use dynamic disc allocation techniques. 

ITie checkpoint operation is not required for Indexed files if no new records are created (that is, if only already-existing 
blocks are being updated). If new records are being created (i.e. , append operations), the checkpoint operation may be 
desirable. 

TRADEOFFS 

In the areas of file structure, buffer management method, and access method, there are many choices which may be 
confusing to the programmer. The following data is presented to assist the programmer in making this choice. 

If pseudo-filemarks are required for magnetic tape emulation, the Contiguous file structure is required. This may be the 
case when magnetic tape-oriented programs are to be used. 

If the maximum length of the file is completely unknown, the Contiguous file is ruled out. Only an open-ended file 
structure will do in this case. Most applications, however, generally define files in such a way that it is possible to make a 
good guess at the maximum length of each data structure. In this case, assuming the disc is not badly checkerboarded, the 
Contiguous file may be considered. (If the disc is checkerboarded, the allocation of a large Contiguous file may not be 
possible.) 

Between the Indexed and Contiguous file structures, if the file is to be read and written using sequential access, the 
Indexed file structure is the obvious choice. If the file is long and is to be accessed randomly, the Contiguous file structure 
is usually preferable. However, this choice is not always clear, for the following reasons: 

Random access may be more or less efficient depending on the average access distance. If the distribution is 
equiprobable, that is, if the likelihood that any one record will be selected for the next data transfer is the 
same as for any other record, the mean search distance is 1/3 of the length of the file. If the distribution is 
highly localized, the Contiguous file structure has few advantages over the Indexed. 

If the REWIND and FORWA,RD-FILE commands (which do not cause disc accesses) are used, the mean 
search distance may be reduced from 1/3 of the file length to 1/6 of the file length. This also tends to make 
the Indexed file look a little better. 
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Once the choice of the Indexed structure has been made, the physical block size must be selected. Cogent reasons have 
been given for keeping the physical block size small. However, a large block size can be very helpful in some cases. The 
main time factors involved in a disc access are seek time (for moving-head discs) and rotational latency time. These times, 
on the average, far overshadow the actual data transfer time. Therefore, a transfer of two or more sectors generally costs 
little more time than a transfer of only one sector. For this reason, the number of disc accesses is the critical figure in 
computing the time required to access a file. A large physical block size can reduce by far the number of accesses. Here it is 
important to consider performance of the overall system. If a given task is not critical, and is running in a multitasking 
environment, other tasks can be active while it waits for disc accesses. If the task is critical, hov/ever, or is running in a 
single-tasking environment, a large physical block size may reduce its running time. 

Finally, if speed of access is paramount and the file size is fixed, the Contiguous file structure should certainly be used. 
There is no time overhead associated with finding data using this file structure. The amount of system overhead used in 
accessing Contiguous files is less than for any other file type. 

The compatibilities between these file types far outweigh their incompatibilities. It is quite possible to write programs that 
can use any or all of these file structures indiscriminately. If programs are written in such a manner, then the user can 
actually try out the application using the various possible file structures in order to find out which is more efficient. In 
addition, the programs are able to use files which may be the output of other dissimilar programs or which may previously 
have existed. 

The Contiguous file is compatible with the Indexed file, providing that the Contiguous files extraordinary treatment of 
filemarks can be ignored. 

CONCLUSIONS 

Tlie OS/16 file structures and access mechanisms are basic building blocks. They are not oriented towards any specific 
application, or toward any specific class of applications. These structures, methods and mechanisms are designed to give 
the user programmer a set of tools. By using these tools one should be able to build a set of data structures specifically 
suited to whatever the application may be. 
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CHAPTER 7 
GUIDE TO USER OVERLAYS 



INTRODUCTION 

In order to minimize tlie amount of memory necessary to run a taslc, OS/16 MT2 allows the user to design a task in 
segments and control those segments such that only those that are necessary must be in memory at any one time. Such a 
task consists of the root segment, which is in memory for the duration of the task, and a number of overlay segments, 
which are brought into memory when necessary, at the task's request. Tliis chapter discusses the use of overlays to reduce 
the memory required to execute a task. 

A task to be overlayed usually is designed as a main program with a number of subroutines. Before being executed under 
OS/ 16 MT2, this main program and its subroutines must be established as a task by the OS/ 16 Task Establisher Task 
(TET/16). TET/16 processes 16-Bit loader format programs and produces memory image load modules. TET/16 resolves 
EXTRN and ENTRY references by linking or editing in the specified programs. References to Task Common and Resident 
Library routines are also processed by TET (see Chapter 1 of this manual and Chapter 4 of the 0SI16 MT2 Operators 
Manual). If no overlay facility is to be used, TET/16 processes the specified main program and subroutines and produces 
one image load module containing all the task's routines and data areas in the order processed. If overlays are to be used, 
TET/16 is used to produce an image load module containing the root segment and multiple areas of reserved space, and 
one or more image load modules that contain overlay segments to be loaded into the space reserved in the main program. 

ROOT AND OVERLAY SEGMENTS 

For an overlayed task, the root segment consists of all the programs, subroutines and data areas that must be in memory 
throughout the execution of the task. At TET time, the user must specify: 

The programs to be linked or edited into the root. 
All Block Data programs used by the task. 

The maximum amount of memory obtained through Get/Release Storage requests or any non-standard 
internal memory requirements. 



The starting address of the partition for which the task is being established. 



To produce overlay segments, the user specifies the programs and Block Data programs to be linked into each overlay and a 
unique name to be associated with the overlay load module. After all the overlays to be loaded into the first overlay area 
have been processed, the user can then specify the overlays to be loaded into a second overlay area. Up to 127 overlay 
areas can be defined in this manner. Overlays to be loaded into the same overlay area are said to be on the same level. 

Figure 7-1 illustrates the organization of a sample memory map for a task using two overlay areas: the image load module 
containing the root segment and any common blocks necessary. This segment reserves space for Get Storage requests and 
for each overlay area. The user must specify the starting address of the partition the task is being established for. After 
processing the routines and data areas to be included in the root, TET reserves the user-specified number of bytes for Get 
Storage requests. If no value is specified, TET uses a value based on the requirements of the FORTRAN Run Time Library 
(RTL). In specifying the Get Storage area, the user must consider Get Storage requests issued by the root and all overlays, 
since all such requests are obtained from this area and any additional non-standard memory requirements of the task. From 
the size of the root segment, TET fixes the start of the first overlay area. The starting address of subsequent overlay areas is 
set to the starting address of the previous overlay area plus the size of the largest overlay produced for that previous area. 
The Get Storage area is reserved above the last overlay area. 
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Figure 7-1. Partition For An Overlayed Task 



OVERLAY CONVENTIONS 



This section discusses the conventions that must be followed in the design of an overlayed task in order to ensure proper 
coordination between the various segments. At execution time, an overlay segment is loaded into memory via an SVC 5, 
Fetch Overlay request. The SVC 5 parameter block specifies the Logical Unit assigned to the file or device containing the 
desired overlay, and the name associated with the overlay at TET time. An overlay load request may be issued by the root 
segment or by an overlay segment with the exception that an overlay must not be loaded in the overlay area occupied by 
the segment requesting the load. SVC 5 returns an error: if the overlay could not be loaded because of an I/O error, a name 
mismatch or the overlay does not fit into memory available (see Chapter 3 for SVC 5 details). The root can reference any 
overlay that is loaded and an overlay can reference the root or any overlay loaded into another overlay area. It is not 
necessary to load an overlay if it is known to be in memory. 

To ensure the proper resolution of external symbols, note the following rules: 

1 . The root segment may reference any entry point in an overlay. If there is more than one occurrence of 
a symbol definition, TET firet tries to resolve the external reference to an entry point within the root 
segment. If not, TET resolves the external reference to the first occurrence of that entry point and 
outputs a 'MULT DEFD' error message for each subsequent occurrence. 

2. The EDIT command causes a subroutine to be included in an overlay if a copy of the subroutine does 
not already exist in that overlay segment or in the root segment. 

3. An overlay segment may reference any entry point in the root segment or any segment in another 
overlay level. An external symbol is resolved to the first of the following: 

a. An entry point within the overlay segment. 

b. An entry point within the root segment. 

c. The first entry point found in any overlay area(s) other than the one in which the reference is 
being made. 

Other entry points of the same name in any other overlay area cause the 'MULT DEFD' error message 
to be output. 
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OVERLAY DESIGN CONSIDERATIONS 



Task Level 



There are many considerations wliicli determine the optimum number of overlay areas and what routines aie loaded into 
the various areas. This section suggests a few of these considerations. 

If one large overlay is to share an area with a number of small overlays, determine if the large overlay could share another 
area with a similar size overlay, thus reducing the size of the first area. In other words, in the absence of coordination 
restrictions, a design which places only overlays of similar sizes in the same overlay area minimizes memory requirements. 
If all routines, referencing a particular common bloclc, form one overlay, then the common block should be part of that 
overlay instead of requiring space in the root segment. If two overlays in the same overlay area communicate via a labeled 
Common block, then that block must be defined and positioned in the root segment or an overlay in another overlay area 
which is in memory during the time the Common block is referenced. 

It may also be possible to use the Get Storage area for temporary storage used by Overlay Segments. If overlays are to use 
this area, it is important to coordinate Get/Release Storage (SVC 2) requests from the overlays with such requests from the 
root segment or from resident library routines. If overlays get the required storage on entry and release the same amount 
on exit, and all overlay segments are invoked as subroutines, the Get/Release requests would be processed in the correct 
order. In calculating the amount of Get Storage area to reserve, the user must consider the maximum number of bytes that 
may be gotten at any one time by the root segment, overlay segments and reentrant library routines. 

System Level 

In designing a series of tasks to be run as a system under OS/ 16 MT2, it is necessary to choose the most efficient partition 
configuration to contain the tasks. The same coordination considerations used in designing an overlay structure enter into 
designing the partitioning structure. The user must decide what tasks must be in memory simultaneously and what tasks 
may share a partition. After deciding which tasks may share a partition, these tasks should be established. The maps 
produced by TET can then be used to choose the starting address for the next partition. After all the partitions have been 
determined, the SET PARTITION operator command can be used to partition the user space. 

OVERLAY EXAMPLE 

Figure 7-1 illustrates the mapping of a partition containing a task with two overlay areas. The root segment consists of the 
User Dedicated Locations, the main program and subroutines, a number of local Common blocks defined in those 
subroutines and 512 bytes of Get Storage area. The first overlay area is designed to hold one of three overlays named ABC, 
DEF, or GHI. The second overlay area is designed to hold one of two overlays named JKL and MNO. Each overlay is to be 
output to a file named XXX.OVY where XXX is the overlay name. Overlay GHI consists of a main routine and several 
subroutines, the remaining overlays consist of a single subroutine. Figure 7-2 illustrates the TET/ 16 commands used to 
establish the task. 
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Figure 7-2. Establish A Sample Overlayed Task 
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CHAPTER 8 
INPUT/OUTPUT PROGRAMMING 



INTRODUCTION 

All input/output requests are made via Supervisor Call SVC 1. SVC 1 is described in general in Chapter 3. This chapter 
discusses the functional aspects of the devices and Direct-Access files supported by OS/ 16 MT2. Included is specific device 
dependent information such as supported functions, status returned, and formatting performed. 

All devices and files support ASCII formatting. Proceed I/O, sequential access and non-unconditional proceed, unless 
otherwise noted in the individual driver or file handler description. The supported attributes listed with each description 
are in addition to those listed previously. 

CONTIGUOUS FILES 

Supported Devices 

Contiguous files are supported on all devices supported by the Moving Head Disc Driver or the Floppy Disc Driver. Device 
Code is 0(0). 

Supported Attributes 

Read, Write, Binary, Wait, Random, Unconditional Proceed, Image, Rewind, Backspace Record, Forward Space Record, 
Write File Mark, Forward Space File Mark, Backspace File Mark. Fixed length 256 byte records. 

Functional Description 

Contiguous files may be accessed either randomly or sequentially. These two access methods may be mixed without closing 
and reassigning the file. Records are accessed by referring to the current record pointer. The current record pointer is a 
number, ranging from zero to one less than the number of sectors allocated to the file. For sequential access, the value of 
the current record pointer, as left by the previous operation, is used to access the file. For random access, the user specifies 
the current record pointer to be used. When a contiguous file is assigned, the current record pointer is set to zero. 

Read: (ASCII, Binary, and Image modes are identical.) The requested data is read from the 

disc, starting at the sector specified by the value of the current record pointer 
(sequential access) or by the random value specified in the SVC 1 call (random access), 
directly into the user specified buffer. The current sector pointer is set to 1 past the 
last sector involved in the transfer. All Reads begin on a sector boundary and end when 
the specified number of bytes have been transferred. 

Write: Same as Read, except the data is transferred from the user specified buffer to the disc. 

If the number of bytes transferred is not an integral multiple of 256, the last byte in 
the buffer is propagated to fill the last sector involved in the transfer. 

Test and Set: Test and Set operation, specified by setfing both Read and Write bits in the SVC 1 

function code (X'60'), is implemented to provide compatibility with previous 
INTERDATA operating systems. Test and Set allows a task to access a file, or sector 
within a file, and at the same time mark it as being in use. Test and Set causes the 
requested data to be read into the specified buffer. Before control is returned to the 
task, the first halfword of the data is checked for a halfword of zero (X'OOOO'). If this 
halfword is zero, it is changed to X'FFFF', the record is rewritten to the file, and 
control is returned to the task with a Condition Code of zero. If the halfword is 
already X'FFFF', control is returned to the task with a Condition Code of X'F'. If the 
halfword is neither zero nor X'FFFF', control is returned with zero Condition Code. 
I/O proceed request for Test and Set (bit 4 of SVC 1 function code reset) is treated as 
a Wait request, except that an I/O Proceed complete queue entry is made, if enabled. 
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Rewind: 

Backspace Record: 
Forward Space Record: 

Write File Mark: 

Forward Space Filemark: 



Back,space File Mark: 



The current record pointer is set to zero. 

The current record pointer is decremented by one. If it is already zero, it is left at zero. 

The current record pointer is incremented by one. If it is equal to one less than the 
number of sectors in the file minus one, it is unchanged. 

A record containing X'13 13' as the first halfword is written to the current record. The 
current record pointer is incremented by one. 

The file is read from the current record until a record containing an X'1313' as the first 
halfword is found. The current record pointer is updated to point to the record 
following the file mark record. If no filemark record is found, the current record 
pointer is set to one less than the number of sectors in the file and End of Medium 
(EOM) status is returned. 

The file is read backwards, starting with the record before the current record, until a 
record containing an X'1313' as the first halfword is found. The current record pointer 
is updated to point to the record containing the filemark. If no filemark record is 
found, the current record pointer is set to zero and End of Medium (EOM) status is 
returned. 



Status Definition 

Status 



Meaning 
X'OO' Normal Completion. 

X'AO' Device Unavailable. 

X'90' End of Medium (EOM). Request results in current record pointer equal to or greater than the number of 

sectors in file. 

X'88' End of File (EOF) Record containing X'1313' as first halfword detected during Read, Write, Forward 

Record or Backspace Record request. 

X'84' Unrecoverable error on device. 

X'82' Data Transfer error after 5 retries. 



NOTE 

Contiguous files are truly random files. Records may be accessed 
in any order. The records are fixed length (256 bytes) and all 
sectors in the file are reserved in a contiguous block at allocate 
time. Contiguous files support a pseudo filemark capability that 
gives them some of the characteristics of a magnetic tape device. 
Since the pseudo filemark is a halfword of X'1313' at the 
beginning of a sector, care should be taken to ensure that this 
datum is not inadvertently written at the beginning of a record. 

INDEXED FILES 

Supported Devices 

Indexed files are supported on all devices supported by the Moving Head Disc Driver or the Floppy Disc Driver. Device 
code is 2(2). 

Supported Attributes 

Read, Write, Binary, Wait, Random, Unconditional Proceed, Image, Rewind, Backspace Record, Forward Space Record, 
Write File Mark, Forward Space File Mark, Backspace File Mark. Fixed length 256 byte records. 

Functional Description 

Indexed files may be accessed either randomly or sequentially. Tliese two access methods may be mixed without closing 
and reassigning the file. Records are accessed by referring to the current record pointer. The current record pointer is a 
number ranging from zero to one less than the number of records in the file. For sequential access, the value of the current 
record pointer, as left by the previous operation, is used to access the file. For random access, the user specifies the current 
record pointer to be used. When an Indexed file is assigned for Exclusive Write Only (EWO) or Shared Write Only (SWO), 
the current record pointer is set to the number of records in the file (the correct value for appending records); for all other 
access privileges, the current pointer is set to zero. 
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Read: 



Write: 



Rewind: 
Backspace Record: 

Forward Space Record: 

Forward Space File Mark: 
Backspace File Mark: 



(ASCII, Binary or Image modes are identical.) Tlie block containing the start of the 
logical record specified by the value of the current record pointer (sequential access) or 
by the random value specified in the SVC 1 parameter block (random access) is read 
into a system buffer (unless it is already in memory). The requested number of bytes 
are moved from the system buffer to the user specified buffer. The transfer ends on 
user buffer full or when a number of bytes equal to the logical record length of the file 
has been moved. The current record pointer is set to the record following the record 
accessed. Any physical reads necessary to complete the transfer are completed by the 
system. 

Same as Read, except the data is moved from the user buffer to the system buffer. The 
system buffer is flushed, whenever necessary, by the system. If a current record pointer 
value of one greater than the last record in the file is specified, a record is appended to 
the file, thus allowing the Indexed file to be extended at any time. If the size of the 
specified buffer is less than the logical record length, the record is padded on the end 
with blanks (ASCII Format) or zeros (Binary Format). 

The current record pointer is set to zero. 

The current record pointer is decremented by one. If already ZERO, it is left 
unchanged and EOF status is returned. 

The current record pointer is incremented by one. If already equal to one less than the 
number of logical records in the file, it is left unchanged and EOF status is returned. 

The current record pointer is set to the number of logical records in the file. 

The current record pointer is set to zero. 



Status Definition 



Status 



X88 



Meaning 

Normal completion. 

End of Medium (EOM). No space available on volume for new index or data block. 

A write request has attempted to set the current record pointer to a value 2 or more than the current 
number of records in the file, or less than zero. A read request has attempted to set the current record 
pointer to a value less than zero or greater than the number of records in the file. 

Unrecoverable error during physical Read or Write. 

Data transfer error after 5 retries during physical Read or Write. 

NOTE 

Control is not returned to the task on I/O Proceed requests until 
completion of the request. Shared Write access is not permitted to 
an Index file. If a Shared Write access privilege (SRW, SWO, 
ERSW) is requested to an Indexed file, the system automatically 
grants exclusive Write access, if possible. 



TELETYPE KEYBOARD /PRINTER 
Supported Devices 



Device 

M33 Teletype Keyboard/Printer 
M35 Teletype Keyboard/Printer 
Non-edit CRT, current loop interface 
Carousel 30/35 80 Char/line 
Carousel 30/35 132 Char/hne 



luct Number 


Device Code 


M46-000/2/4/5 

M46-001/3 

M46-100/1 

M46-0 10/0 15/0 11/016 

M46-010/01 5/01 1/016 with M46-880 


16(10) 
17(11) 
18(12) 
21(15) 
22(16) 
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Supported Attributes 

Read, Write, Wait, Unconditional Proceed, Image, Interactive, Halt I/O 
Variable Record Length up to 72 characters (16), 80 characters (17, 18, 



21), 132 characters (22) 



Functional Description 
Read ASCII: 



Data read is masked to 7-Bit ASCII. Data is read until the buffer is full, or a carriage return is 
found, whichever occurs first. Upon termination, a Carriage Return-Line Feed sequence is sent 
to the printer. Typing the character W csuses the line input to be ignored, a Carnage 
Return-Line Feed sequence to be output, and the Read operation to be restarted. Typing the 
character ' ■•— ' or the BS character, causes the previous character entered to be ignored. 



Write ASCII: 

Read or Write Image : 

Status Definition 

Status 



X'82' 
X'84' 
X'AO' 



The buffer is scanned to eliminate trailing blanks. Data is then output until the buffer is 
exhausted or until a carriage return is found in the data stream. A line feed is automatically 
appended to the detected Carriage Return, or if no Carriage Return was detected, a Carriage 
Return-Line Feed sequence is output. 

None of the above formatting actions occur. The amount of data requested is typed out or 
read in, without masking to 7-Bit ASCII, eliminating trailing blanks, checking for '# , .4- or 
BS characters, or detecting or appending carriage returns or line feeds. On Image read, how- 
ever, a Carriage Return is detected as an end-of-line sentinel. 



Meaning 

Normal Completion 
Time out or Line Break 
Unrecoverable Error 
Device Unavailable 



NOTE 

The Reader/Punch of an ASR TTY is treated as a separate device 
but may not be active at the same time as the Keyboard/Printer. 
It is assigned by requesting the device for shared read only access 
(SRO). 



TELETYPE READER/PUNCH 
Supported Devices 

Device 

M33 TTY Reader/Punch 
M35 TTY Reader/Punch 
Carousel 35 Reader 



Product Number 
M46-000/2/4/5 
M46-001/3 
M46-821 



Device Code 

81 (51) 

82 (52) 

83 (53) 



Supported Attributes 

Read, Write (except for Carousel Reader), Binary, Wait 
Variable Length Records. 

Functional Description 



Unconditional Proceed, Image, Halt I/O 



Read ASCII: An X-ON character is output to turn the reader on. Tape is read in blocked mode so data is not 

printed on the printer while it is being read. Leading blank frames and Delete characters are ignored. 
Data is masked to 7-Bit ASCII. The transfer is terminated on buffer full or Carriage Return, 
whichever occurs first. On termination of the transfer, tape is advanced to the next Delete character 
or blank frame. An X-OFF character is output to stop the tape. 
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Read Binary: An X-ON character is output to turn on the tape. Tape is slcipped until the first non-blanic frame is 

found. If the first non-blanlc character read is a X'FO', the following frames are read in until the user 
buffer is full. This is non-zoned binary format. If the first non-blank character read is not a X'FO', 
zoned binary mode is assumed. In this case, the characters are read, stripped of the zones and 
packed into the user buffer until buffer full. In this mode the only valid punches are X'90', 
X'8r-X'84', X'95'-X'9F'. Other characters are ignored. On buffer full, the tape is advanced to the 
next blank frame in zoned binary mode. Note that in unzoned binary, the first character transferred 
to the user buffer is the character following the X'FO' character, while in zoned binary, the first 
non-blank frame is transferred (after stripping and packing). After the request is satisfied, an X-OFF 
is output to turn off the reader. 

Read Image: None of the above formatting operations is performed. An X-ON character is output to turn the 

tape on, data is read until user buffer full, the X-OFF character is output to turn the tape off and 
the transfer is complete. 

Write ASCII: Tlie driver outputs a RUBOUT-TAPE-RUBOUT-RUBOUT sequence in order to initialize the TTY 

reperforator. Eight frames of blank tape are output as leader, the user data is output until buffer 
empty or Carriage Return, whichever occurs first. The driver ensures that a CR-LF-TAPE 
OFF-RUBOUT sequence terminates the record. 

Write Binary: The driver outputs a RUBOUT-TAPE-RUBOUT-RUBOUT sequence, followed by eight blank 

frames of leader. The user buffer is output, translating each byte into two frames of zoned binary 
data. The transfer is terminated on buffer empty. The driver then outputs a TAPE OFF-RUBOUT 
sequence. 

Write Image: None of the above formatting or control operations are performed. The user buffer is output until 

buffer empty. 



Status Definition 

Status 

x'oo' 
x'ao' 

X'84' 
X'82' 



Meaning 

Normal completion 

Device unavailable 

Data transfer error. 

Break detected during transfer. Timeout. 

NOTE 

On ASCII or Image write, it is possible to turn off the punch 
inadvertently by outputting a TAPE OFF character. On Image 
write it is the responsibility of the user to place the necessary 
control characters, such as TAPE and TAPE OFF in the user 
buffer to control the operation of the tape. 

Since the Reader/Punch portion of the TTY is connected to the 
Keyboard/Printer portion, only one of these devices may be active 
at a time. On ASCII write, the data punched on the tape is also 
printed on the printer. The reader/punch is requested by 
assigning the device for shared read only (SRO) access. 



LOCAL CRT 
Supported Devices 

Device 

Non Editing CRT (PALS or PASLA) 

Graphic Display Terminal (PALS or PASLA) 

Carousel 300 Keyboard/Printer (PALS or PASLA) 

Carousel 300 Keyboard/Printer 
Electronic Format Control 



Product Number 


Device Code 


M46-100/1 


34(22) 


M46- 108/9 


36(24) 


M46-803/4 


37(25) 


M46-803/4 with M46-887 


38(26) 



All are supported via PALS or PASLA, M46-106 null modem (cable). 



Supported Attributes 

Read, Write, Wait, Unconditional Proceed, Image, Interactive, Halt I/O. 
Variable length records up to 80 characters (34, 36), 132 characters (37, 38). 
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Functional Description 
Read ASCII: 



Write ASCII; 



Read or Write Image: 



Data read is masked to 7-Bit ASCII. Data is read until the buffer is full, or a Carriage Return is 
found, whichever occurs first. Upon termination, a Carriage Return-Line Feed sequence is sent to 
the printer Typing the character '# 'causes the line input to be ignored, an LF/CR/CR sequence to 
be output, and the Read operation to be restarted. Typing the character "*J', or the character BS, 
causes the previous character entered to be ignored. 

The buffer is scanned to eliminate trailing blanks. Data is then output until the buffer is exhausted 
or until a Carriage Return is found in the data stream. A Line Feed is automatically appended to the 
detected Carriage Return or if no Carriage Return were detected, a LF/CR/CR sequence is output. 

None of the above formatting actions occur. The amount of data requested is typed out or read in, 
without masking to 7-Bit ASCII, eliminating traihng blanks, checking for '#', V, or BS characters, 
or detecting or appending Carriage Returns or Line Feeds. On Image read, however, as ASCII 
Carriage Return is detected as an end-of-Une sentinel. 



Status Definition 




Status 


Meaning 


xbo' 


Normal Completion 


X'82' 


Time out or Break. 


X'84' 


Unrecoverable I/O Error. 


X'AO' 


Device Unavailable. 



HIGH SPEED PAPER TAPE READER/PUNCH 



Supported Devices 

Device 

High Speed Paper Tape Readfcr/Pundi 



Product Number 

M46-242/3 



Device Code 
80(50) 



Supported Attributes 

Read, Write, Binary, Wait, Unconditional Proceed, Image. Variable record length. 

Functional Description 

Read ASCII: Leading blank tape and delete characters are ignored. Data is masked to 7-Bit ASCII. Carriage 

Return terminates Read. On termination, the tape is advanced until blank tape or a Delete character 
is read. 

Read Binary: Tape is advanced until a non-zero character is read. If this character is X'FO', the tape is read until 

the buffer is full (Unzoned binary). If the first non-zero character is not X'FO", the tape is treated as 
a zoned binary tape. Each two characters are stripped of their zone and merged into one byte and 
placed in the buffer until buffer is full. On buffer full, the tape is advanced until blank tape is 
found. In zoned binary mode the only valid characters are: X'90', X'81'-X'84', X'95'-X'9F'. All 
other characters cause the transfer to end with unrecoverable status. 

Read Image: Tape is read until buffer is full. None of the above formatting or control operations are performed. 

Write ASCII: Eight frames of blank tape are output. The user buffer is output up to (but not including) Carriage 

Return or until buffer empty. Carriage Return-Line Feed is then output. 

Write Binary: Eight frames of blank tape followed by the character X'FO' are output. The user buffer is output 

until buffer empty. 

Write Image: The user buffer is output until buffer empty. None of the above formatting or control operations 

are performed. 
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Status Definition 

Status Returned 

X'OO" 
X'AO" 
X'82' 
X'84' 



Meaning 

Normal Completion 

Device Unavailable 

Time-out 

Transfer Error or invalid zone character 



LINE PRINTER 
Supported Devices 

Device 

Low Speed (200 LPM) Line Printer 

High Speed (600 LPM) Line Printer 

Supported Attributes 

Write, Wait, Unconditional Proceed, Image. Variable record length up to 132 bytes. 

Functional Description 



Product Number 


Device Code 


M46-204/5/207/8 


112(70) 


M46-209/10 


114(72) 



Write ASCH: 

Write Image: 

Status Definition 

Status 

X'OO' 
X'AO' 

X'84' 



Tlie user buffer is output until a Carriage Return is found or until the buffer is empty. At the 
termination of the buffer, the system takes all necessary action to ensure that tlie buffer is printed 
and the paper spaced upwards one line. If form-feed or any other paper motion is desired, the 
appropriate characters must appear in the user's buffer. 

The user buffer is output exactly as found in memory. No action is taken by the system to ensure 
that the data is printed or that the paper is properly moved. The user should be familiar with the 
characteristics of the particular device being used. 



Meaning 

Normal Completion. 

Device Unavailable. Device not ready. Form error. 

Device became unavailable during transfer 

NOTE 

Although the Low and High Speed Line Printers have different 
form control characters, the sequence Carriage Return, X'Ol' 
causes a new line to be started on each printer. This sequence is 
used for Write ASCII to allow program compatibility using the 
same driver. 



CARD READER 

Supported Devices 

Device 

Card Reader Interface Without Translation 
Card Reader Interface With Translation 



Product Number 

M46-235 

M46-235 with M46-234 



Device Code 

96(60) 
97(61) 



Supported Attributes 

Read, Wait, Unconditional Proceed, Image. Fixed record length 80 bytes (ASCII), 160 bytes (Image). 

Functional Description 

Read ASCII: Each card column (12 bits) is converted into one 7-Bit ASCII character. Illegal codes are converted 

into the null character (X'OO'). 
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Read Image: 



Each column is converted into one halfword with the following format; 
12 3 4 5 6 7 



bit 



card column 



U 



U 



12 



11 







1 



bit 


8 


9 


10 


11 


12 


13 


14 


15 


card column 


U 


U 


4 


5 


6 


7 


8 


9 




u = 


undefined 











Status Definition 

Status 

X'OO' 
X'AO' 
X'84' 



Meaning 

Normal end of transfer. 

Device unavailable. Reader not ready ; Hopper empty or Stacker full. 

Data Transfer error (Read check or Pick check) 



MOVING HEAD DISC 
Supported Devices 

Device 

2.5 Mbyte Removable Cartridge 
5.0 Mbyte Fixed Cartridge 
5.0 Mbyte Removable Cartridge 
40 Mbyte Removable Cartridge 
67 Mbyte Removable Cartridge 
256 Mbyte Removable Cartridge 

Supported Attributes 

Read, Write, Binary, Wait, Random, Unconditional Proceed, Image. Variable Length Records. 



Product Number 


Device Code 


M46-445/6 


49(31) 


M4 6-440/1 


50(32) 


M46-440/1 


51(33) 


M46-429/30 


52(34) 


M46-600/2 


53(35) 


M46-604/6 


54(36) 



Functional Description 



Read: 



Write: 



A current sector pointer is maintained. On a sequential read, data is read from the disc starting at 
the current sector into the user buffer until the buffer is full. If an attempt is made to read beyond 
the end of the disc, end of medium status is returned. On a random request, the data is read from 
the disc starting at the sector specified by the random sector address passed with the request, until 
buffer full. ASCII, Binary, and Image requests are treated identically. 

Data is written from the user buffer to the disc, starting at the current sector for sequential writes 
or at the specified sector for random writes, until buffer empty. Attempts to write past the end of 
the disc cause end of medium status to be returned. In this case, no data is transferred. 



Errors on data transfers cause the operation to be retried ten times before returning error status. 
All data transfers start on a sector boundary but may end on any byte of a sector. 

Status Definition 

Status Meaning 

X'OO' Normal completion. 

X'AO' Request could not be started, device not ready. 

X'90' End of medium. Transfer ends beyond the end of the disc. 

X'88' Pseudo end of filemark read. This status is only returned on request by the OS/ 16 File Manager. 

X'84' Seek incomplete. All device errors other than data transfer error. 

X'82' Data transfer error after ten retries. Write protection violation. Timeout. 
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NOTE 

The Moving Head Disc Driver is designed for use by tlie OS/ 16 
MT2 File Manager. The Disc Driver cannot be invoked by a user 
program unless it is an E-taslc. For user tasks, the disc is acces- 
sed by means of the Contiguous or Indexed file handlers dis- 
cussed in the first section of this chapter. 

The 10 Mbyte Disc System, Product Number M46-440/1, is 
supported in OS/16 as two 5.0 Mbyte cartridges, one fixed and 
one removable. Since there is only one seek mechanism, the 
two discs on a 10 Mbyte system share a busy flag and only one 
disc may be active at any instant in time. 



FLOPPY DISC 
Supported Devices 

Device Product Number Device Code 

Floppy Disc Drive M46-632/638/633/639/630/636/631/637 55(37) 

Supported Attributes 

Read, Write, Binary, Wait, Random, Unconditional Proceed, Variable Length Records. 
Functional Description 

Read : A current sector pointer is maintained. On a sequential read, data is read from the disc starting at 

the current sector into the user buffer until the buffer is full. On a random request, the data is read 
from the disc starting at the sector specified by the random sector address passed with the request, 
until the buffer is full. If an attempt is made to read beyond the end of the disc, end of medium 
status is returned with no data transferred. ASCII, Binary, and Image requests are treated identi- 
cally. 

Write; Data is written from the user buffer to the disc, starting at the current sector pointer (for sequential 

writes) or at the specified sector (for random writes), until buffer empty. If an attempt is made to 
write beyond the end of the disc, end of medium status is returned with no data transferred. ASCII, 
Binary, and Image requests are treated identically. 

Errors on data transfers cause the operation to be retried ten times before returning error status. 

All data transfers start on a logical 256 byte sector boundary (two physical sectors on the disc). A transfer may end on any 
byte of a sector. 

Status Definition 

X'OO' Normal completion. 

X'AO' Request could not be started, device not ready. 

X'90' End of medium. Transfer ends beyond the end of the disc. 

X'88' Pseudo end of filemark read. This status is only returned on request by the 08/16 File Manager. 

X'84' All device errors other than data transfer error. 

X'82' Data transfer error after ten retries. Write protection violation or Time-out. 

NOTE 

The Floppy Disc Driver is designed for use by the OS/ 16 File 
Manager. The Driver cannot be invoked by a user program unless it 
is an E-task. For user tasks, the disc is accessed by means of the 
Contiguous or Indexed file handlers discussed in the first section 
of this chapter. 
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CASSETTE 

Supported Devices 

Device 

Intertape Cassette Drive 

Supported Attributes 



Product Number 



M46-400 



Device Code 



66(42) 



Read, Write, Binary, Wait, Unconditional Proceed, Image, Rewind, Backspace Record, Forward Space Record, Write File 
Mark, Forward Space File Mark, Backspace File Mark. Variable length Records. 



Functional Description 



Read: 



Write: 



Status Definition 

Status 

X'OO' 
X'CO" 
X'AO' 
X'90' 
X'88' 
X'84' 
X'82' 



(ASCII, Binary, and Image modes are identical). Data is read from the cassette into the user's 
buffer. The transfer terminates at buffer full, or at end of record, whichever comes first. If the 
record is longer than the buffer, error status is not returned. Parity errors in the unread part of the 
record, however, may be detected. If a parity error occurs, five retries are attempted before error 
status is returned. On parity error status return, the tape is positioned in the inter-record gap 
following the errored record. 

(ASCII, Binary, and Image modes are identical.) Data is written from the user's buffer until the 
buffer is empty. The system retries five times on parity errors. 



Meaning 

Normal completion. 

Attempt to transfer less than 4 bytes. 

Device not ready. Tape failed to move at start of request. 

End of tape on Read, Write or Write File Mark. 

End of file 

Device became unavailable during a request. 

Data transfer error after 5 retries; time-out. 



NOTE 

The driver cannot distinguish between Beginning Of Tape (BOT) 
and End Of Tape (EOT) conditions. Either condition generates an 
End Tape (ET) condition. If ET is detected on a request, with no 
previous request which causes forward motion, then BOT is as- 
sumed. The user should ensure that a cassette is not loaded at End 
Of Tape unless that condition is expected. 

Since the two drives on an Intertape Cassette share logic, a shared 
busy condition exists and only one drive of a cassette pair 
(e.g.:X'45' and X'55') may be active at a time. Also Keys and 
Access Privileges are shared so the two drives may not be assigned 
with uncompatible privileges. 

Continuous mode operations are used where allowed when 
requests are passed to the driver within the time required 
(lO-milliseconds for Read; 30 milliseconds for Backspace). 



9 TRACK MAGNETIC TAPE 
Supported Devices 

Device 

9 Track 800 Bpi Magnetic Tape Interface 
9 Track 1600 Bpi Magnetic Tape Interface 



Product Number 

M46-470 
M46-475 



Device Code 

64(40) 
65(41) 
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Supported Attributes 

Read, Write, Binary, Wait, Unconditional Proceed, Image. 

Rewind, Backspace Record, Forward Space Record, Write File Mark, Forward Space File Mark, 

Backspace File Mark, Variable Length Records. 



Functional Description 

Read: 



Write: 



Data is read into the user buffer from the magnetic tape. The transfer ends on buffer full or end of 
record, whichever comes first. If the record is longer than the user buffer, error status is returned. 
This error status is indistinguishable from true parity error. On a parity error, five retnes are 
attempted before error status is returned. .After a parity error the tape is positioned m the 
inter-record gap following the errored record. 

Data is written from the user buffer to the magnetic tape until the buffer is empty. Five retries are 
attempted on parity error. 



For both Read and Write requests, ASCII, Binary, and Image requests are identical. 
Status Definition 

Status Meaning 

X'OO' Normal completion. 

X'AO' Device not ready. Tape unavailable at the start of request for data transfer. 

X'90' End of tape. Request caused the reflective marker at end or beginning of tape to be sensed. 

X'88' End of file. Filemark detected during request. 

X'84' Device became unavailable during request. 

X'82' Data transfer error after 5 retries. Timeout occurs. 

NOTE 

The driver cannot distinguish between Beginning Of Tape (BOT) 
and End Of Tape (EOT) conditions. Either condition generates an 
end tape (ET) condition. The driver assumes that if ET is detected 
on a Write request that the tape is at BOT. Issuing a Write request 
at EOT will hang up the controller such that no further interrupts 
may be serviced. If rewind is issued at BOT, the driver simply 
returns normal status. The user should ensure that the tape is 
loaded at BOT unless some other condition is expected. Backspace 
File Mark to a tape with no filemarks between the position of the 
tape and the point of BOT also hangs up the controller. The 
Processor Initialize key must be used to clear this condition if no 
clock exists to time out the driver. 



7-TRACK MAGNETIC TAPE 
Supported Devices 

Device 

7 Track 800 Bpi Magnetic tape interface 



Product Number 
M46-474 



Device Code 
67(43) 



Supported Attributes 

Read, Write, Binary, Wait, Unconditional Proceed, Image Rewind, Backspace Record, Forward space. Record, Write File 
Mark, Forward Space File Mark, Backspace File Mark. Variable Length Records. 



Functional Description 

Read: 



Read ASCII: 



Data is read into the system buffer from the magnetic tape. This buffer is 342 bytes 
long. The transfer ends on buffer full or end of record, whichever comes first. If the 
record is longer than the system buffer, error status is returned. This error status is 
indistinguishable from the parity eiTor. On a parity error, five retries are attempted 
before error status is returned. After a parity error the tape is positioned in the 
inter-record gap following the errored record. 

If no error occurs, the record is then formatted as follows: 

Each byte from the system buffer is converted to 7-bit ASCII and stored in the user 
buffer. This conversion continues until end of user buffer or end of record, whichever 
comes first. 
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Read Binary: 

Read Image: 
Write ASCII: 

Write Binary: 
Write Image: 



Every 4 bytes from the system buffer are converted to three 8-bit binary bytes and are 
stored in tlie user buffer. This conversion continues until end of user buffer or end of 
record, whichever comes first. 

Data is read directly from the magnetic tape into the user buffer. None of the 
previously described conversions take place. 

Bach byte from the user buffer is converted to 6-bit CDC compatible 7 track code. 
Bytes other than carriage return X'OD' outside the range X'20' X'SF'are converted to 
blanks and error status is not returned. If the size of the user buffer is larger than 342 
bytes. Illegal function status is returned. After the described conversion, the systeni 
buffer is written to the tape. Five retries are attempted on parity error. 

Every 3 bytes from the user buffer are converted to four 6-bit bytes and are stored in 
the system buffer. If the size of the user buffer is larger than 256 bytes, Illegal 
function status is returned. After the described conversion, the system buffer is written 
to the tape. Five retries are attempted on parity error. 

Data is written directly from the user buffer onto the magnetic tape. All data bytes are 
masked to 6 bits by the device. Five retries are attempted on parity error. 



Status Definition 

Status 

X'OO' 

X'CO' 

X'AO' 

X'90' 

X'88' 

X'84' 

X'82' 



Meaning 
No Errors 

Illegal Function The user's buffer is too lonj.; with respect to the length of the system buffer. 
Device Unavailable The magnetic tape unit is off-line. 

End-of-Medium — The end of tape or beginning of tape markers have been detected. 
End-of-File — A Filemark has been detected. 
Unrecoverable Error - Device became unavailable during request. 
Recoverable Error - Data transfer error after 5 retries. Timeout occurs. 



EIGHT LINE INTERRUPT MODULE 
Supported Devices 

Device 

Eight Line Interrupt Module 



Product Number 
M4 8-001 



Device Code 
128(80) 



Supported Attributes 

SINT 

Functional Description 

The Eight Line Interrupt Module provides eight interrupt lines to the processor from external equipment and acknowledges 
interrupts on a priority basis. Any line may be selectively enabled or disabled. Several lines may be concurrently enabled. 
An interrupt does not transfer any data, nor is any status given. For details on the functions supported, see the SVC 6 
description in Chapter 3. 

Status Definition 

See SVC 6 error codes in Chapter 3. 
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DIGITAL MULTIPLEXOR 

Supported Devices 

Device Product Number 

Digital Multiplexor M07-860 

Supported Attributes 

Read, Write, Wait, Unconditional Proceed, Image, Binary, Random. 
Functional Description 



Device Code 
129(81) 



Read: 

Write: 

Status Definition 

Status 

X'OO' 
X'AO' 



The second byte of the random address field contains the segment and point number to be read. 
Data is read from the point specified until the buffer specified by the starting and ending address is 
full. 

The second byte of the random address field contains the segment and point number to be written 
to. Data is written until the buffer specified by the starfing and ending address is exhausted. 



Meaning 

Normal completion 
Device unavailable 



CONVERSION EQUIPMENT 
Supported Devices 

Device 

Conversion Equipment Controller 
Conversion Equipment Controller 
(w/external clock) 



Product Number 

M48-603 

M48-603 



Device Code 

136(88) 

137(89) 



Supported Attributes 

Read, Write, Binary, Wait, Random, Unconditional proceed, Halt I/O 



Functional Description 

The SVC 1 Parameter Block for Conversion Equipment is redefined in order to fully support the capabilities of the 
hardware in conformance with the proposed ISA standards. The formats of the parameter block and function byte are 
shown below. 
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FUNCTION 



DEVICE INDEPENDENT STATUS 



LU 



DEVICE DEPENDENT STATUS 



A (START) /A (POP QUEUE) 



A (END) 



RANDOM ADDR/A (RANDOM ADDR LIST) 



A (PUSH QUEUE) 



LENGTH OF TRANSFER 
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The Random function code bit is redefined to mean continuous and is applicable to the read function. ASCII and binary 
modes are identical. 

On Write operations, the user buffer (which must be an integral multiple of two halfwords long) is assumed to contain 
sequential pairs of alternating Digital-to-Analog Converter addresses, and data to be converted, i.e., address, data, address, 
data, etc. The addresses and data are passed to the Real-Time Analog System Controller. It is the user's responsibility to 
ensure conformance with the formats contained in the Conversion Equipment Controller Instruction Manual, Publication 
Number 29-3 1 2, and the restrictions of the user's D-to-A hardware. 

On Intermittent (non Continuous) Read operations, the Random Address field of the parameter block is assumed to 
contain the start address of a table equal in length to the user's buffer (START to END), containing a list of Analog- 
to-Digital Converter addresses. The digitized data obtained is placed in the user buffer. 

On Continuous Read operations, several fields of the parameter block are interpreted in a unique manner. The 
"A(START)" and A(END) fields must contain the address of the "Pop Queue". The first halfword of the Random Address 
field is assumed to contain the address of the "Random Address List", and the next halfword is assumed to contain the 
address of a "Push Queue". Each entry in a queue (Circular List) is assumed to be the address of a buffer block 32 
halfwords long for the "Random Address List", and 33 halfwords long for the "Pop" and "Push" queues. 

Buffer blocks in the "Random Address List" are assumed to contain 32 halfwords of Analog-to-Digital converter addresses, 
which are passed to the Controller in sequence. Entries are removed from the bottom of the list and then added back to 
the top of the list. By filling this list with an appropriate set of entries, the user may thereby effect a continuous scan of 
A/D converters in any sequence he desires, either random or sequential. 

Upon completion of a conversion cycle of 32 A/D addresses, an entry is removed from the bottom of the "Pop Queue". 
The address of the appropriate entry from the "Random Address List" is placed in the first halfword of the "Pop" buffer 
block, and the digitized data in the remaining 32 halfwords. The address of the buffer block is then added to the top of the 
"Push Queue". Upon the initial SVC call, the "Push Queue" should be empty, and the "Pop Queue" should contain entries 
of vacant buffer blocks. The user should thereafter monitor the status of the "Push Queue" at a rate consistent with the 
conversion rate of his equipment and the number of entries in the "Pop Queue". When an entry is found to have been 
added to the "Push Queue", it should be removed (from the bottom, if FIFO ordering is to be preserved), the data 
processed, and another vacant block added to the "Pop Queue". 

The continuous read operation terminates on one of four possible conditions; Address List Underflow, Pop Queue 
Underflow, Push Queue Overflow, or a halt I/O request. The effects of the first three conditions are described under Status 
Definitions. The last condition is provided to allow the user a rapid means of terminating the operation. Length of data 
transfer field is undefined on a Continuous Read operation. 

On Auto-Range operations, specified by setting both the read and the write bits of the function code, the Random Address 
field of the SVC 1 Parameter Block is assumed to contain the address of "n" pairs of halfwords, the first containing the 
address of the ADC chassis. The next halfword of each pair should contain a control word specifying auto-ranging, the 
channel address, and the starting gain, "n" pairs of halfwords specifying the digitized data (first halfword) and channel 
address and final gain (second halfword) will be returned in the user's buffer. N is equal to A(START) - A(END))/4. 

It should be noted that, if the "Pop" and "Push" Queue addresses specify the same queue, then the possibility of queue 
overflow or underflow is eliminated. After one complete conversion cycle, the queue will always contain the most recently 
converted data. 



Status Definition 

The error conditions monitored by the driver resulting in an error status returned in the second halfword of the SVC 1 
parameter block are as follows; 



STATUS 


MEANING 


X'AO' 


Device Unavailable 


X'84' 


Unrecoverable Error 


X'90' 


Address List Underflow 



This status condition is set on Continuous Read operations, if when attempting to obtain a block of 
ADC addresses from the "Random Address List", the list is found empty. The operation then 
terminates. 
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STATUS MEANING 

X'88' Pop Queue Underflow 



X'98' Push Queue Overflow 



This status condition is set on Continuous Read operations, if, when attempting to obtain a vacant 
data bloclc from the "Pop Queue", the queue is found empty. The operation then termmates. 

Push Queue Overflow 

This status condition is set on Continuous Read operations, if, when attempting to add a data block to 
the "Push Queue", list overflow occurs. The block is returned to the bottom of the 'Pop Queue , and 
the operation terminates. 

X'82' Time Out 

This status condition is set on all operations if the controller fails to generate an interrupt witMn two 
seconds. 
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CHAPTER 9 
GUIDE TO WRITING DRIVERS 



INTRODUCTION 

Drivei-s for non-standard devices may be readily included in OS/ 16 MT2 provided these drivers are written to conform with 
those procedures used in writing standard drivers. Standard drivers are designed to minimize the period of time external 
interrupts are disabled. To this end, all drivers consist of at least two, and sometimes three or four distinct parts. The first 
part or module required in all drivers, is the initialize routine. In operation, this part of the driver becomes a subroutine of 
the Executive, which runs with external interrupts enabled. The initialize routine interprets the function code, and in 
general, performs any preliminary function that can be done with interrupts enabled. The second module of the driver is 
the interrupt service routine. This is an independent routine, although assembled along with other parts of the driver. The 
third module which, depending on the type of device and the needs of the user, may not be required, is the termination 
routine. Like the initialize routine. It becomes a subroutine of the executive and performs such functions as error 
identification, code conversion, and interpretation of final device status. The fourth module is the abort routine, which 
stops on-going I/O when a cancel request is made. 



The DEVICE CONTROL BLOCK 

A fifth module, not technically part of the driver, is required for all devices on the system. This is the Device Control Block 
(DCB). One DCB is required for each device on the system. However, if the driver is properly coded, only one copy of the 
driver is needed to control several devices of the same type. The Device Control Block provides external storage locations 
for the driver. Thus, it is possible, using indexed instructions when referring to the DCB, for the driver to handle more than 
one device Drivers and system routines reference locations in the DCB with indexed instructions. General Register 14 
should always be used as the index register to the DCB. A DCB for each device including user-written driver devices, is 
automatically generated by the Configuration Utility Program (CUP/16), when the device is configured. 

The DCB consists of two main sections, the device independent portion which is described in detail below (the same for all 
devices), and an optional device dependent portion which consists of additional storage areas that a driver may need for 
operation of a particular device. For example, a Mag Tape driver may need a storage location for a Selector Channel device 
number or flag. If a user-written driver requires a device dependent section, the user may edit the source of the 
CUP-generated DCB, prior to assembly, to add additional storage locations (e.g. DS 8). 

A map of the standard DCB is shown in Figure 9-1 . The symbol 'DBxxxx' is the address of the DCB. Reference to elements 
of the DCB can be made symbolically from the DCB address. The STRUC in Figure 9-2 defined DCB elements. For 
example, the device code at DCB-18 may be referred to by DCB.DC0D(R14). The following section discusses DCB 
elements as pertains to user-written drivers. 
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DCB.PPSW 

DCB.RECL 
DCB.CNTS 

DCB.ATRB 

DCB.KEYS 

DCB.BUSY 

DCB.TERM 

DCB.ALOC 

DCB.TOUT 

DCB.FLGS 

DCB.INIT 

DCB.OPSW 

DCB.NPSS 

DCB.ENTR 

DCB.LEAV 
DCB.NOPI 

DCB.RSAV 



DCB.ISR 
DCB.RES 



-24 






PARAMETER BLOCK PSW 


■22 






MAXIMUM RECORD LENGTH 


-20 


DCB.WCNT 

WRITE COUNT 


DCB.RCNT 
READ COUNT 


-18 


DCB.DCOD 

DEVICE CODE 


DCB.DN 

DEVICE NO. 


-16 






ATTRIBUTES 


■14 


DCB.WKEY 

WRITE KEY 




DCB.RKEY 
READ KEY 


-12 


DCB.SBSY 


A(BUSY FLAG) 


-10 






A(TERM ROUTINE) 


-8 






A(ABORT ROUTINE) 


-6 






TIME-OUT COUNT 


-4 






FLAGS 


-2 






AdNITIALIZATION ROUTINE) 


0(0) 






OLD PSW 


4(4) 






NEW PSW STATUS 


6(6( 






STM R8,I0RSAV 

LM R8,REG8xxxx 

BR R15 

STM R8,REG8xxxx 

LM RS.IORSAV 

LPSW DBxxxx 


28(1C) 


R2 




CALLER TCB POINTER AND DCB.IOW 
I/O WAIT POINTER 


30(1E) 


R3 




A(PARBLK) 


32(20) 


R4 




FUNCTION CODE AND LU 


34(22) 


R5 




MAY BE USED BY DRIVER 


36(24) 


R6 




DEVICE NUMBER 


38(26) 


R7 




STATUS 


40(28) 






R8-R13 


52(34) 


R14 




A(DCB) 


54(36) 


R15 




A(ISR) 


56(38) 






BUSY FLAG 



DBxxxx 



REGSxxxx 



Figure 9-1. Device Control Block Map 
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DCB.PPSW 

DCB.RECL 

DCB.CNTS 

DCB.WCNT 

DCB.RCNT 

DCB.DCOD 

DCB.DN 

DCB.ATRB 

DCB.KEYS 

DCB.WKEY 

DCB.RKEY 

DCB.BUSY 

DCB.SBSY 

DCB.TERM 

DCB.ALOC 

DCB.TOUT 

DCB.FLGS 

DCB.INIT 

DCB.OPSW 

DCB.NPSS 

DCB.ENTR 

DCB.LEAV 

DCB.NOPI 

DCB.IOW 

DCB.RSAV 

DCB.ISR 

DCB.RES 



EQU 

EQU 

EQU 

EQU 

EQU 

EQU 

EQU 

EQU 

EQU 

EQU 

EQU 

EQU 

EQU 

EQU 

EQU 

EQU 

EQU 

EQU 

STRUC 

DS 

DS 

DS 

DS 

DS 

EQU 

DS 

EQU 

DS 



-24 
-22 
-20 
-20 
-19 
-18 
-17 
-16 
-14 
-14 
-13 
-12 
-12 
-10 

- 8 

- 6 

- 4 

- 2 

4 

2 

10 

4 

8 

*+l 

14*2 
»_2 

n 



PARAMETER BLOCK PSW 

LOGICAL RECORD LENGTH 

COUNTS 

WRITE COUNT 

READ COUNT 

DEVICE CODE 

DEVICE # 

DEVICE ATTRIBUTES 

KEYS 

WRITE KEY 

READ KEY 

A (BUSY FLAG) 

A (SELCH BUSY FLAG) 

A (TERMINATION ROUTINE) 

ABORT LOC 

TIME OUT COUNT:0=TIMED OUT 

FLAGS HALFWORD 

A (INITIALIZATION ROUTINE) 

OLD PSW SAVE AREA 

NEW PSW STATUS 

INTERRUPT SERVICE ENTRY POINT 

INTERRUPT SERVICE EXIT LOCATION 

NOP ISR ENTRY 

I/O WAIT POINTER 

SAVE AREA FOR REGISTERS 2-15 

ISR POINTER (Rl 5) 

RESERVED FOR BUSY FLAG 



-2B 
-2B 
-2B 
-IB 
-IB 
-IB 
-IB 
-2B 
-2B 
-IB 
-IB 
-2B 
-2B 
-2B 
-2B 
-2B 
-2B 
-2B 



-IB 

-2B 



DFLG, 
DFLG. 
DFLG 
DFLG 
DFLG 
DFLG 
DFLG 
DFLG. 
DFLG 
DFLG 
DFLG 
DFLG 
DFLG 
DFLG 



BLM 
LNM 
BBM 
MPM 

PFM 
.BMM 
.CNM 
.BIM 
.S6M 
.WPM 

HIM 

SIM 
.SOM 

lUM 



DATR.INM 

DATR.RDM 

DATR.WRM 

DATR.BIM 

DATR.WTM 

DATR.RNM 

DATR.UPM 

DATR.IMM 

DATR.HIM 

DATR.RWM 

DATR.BRM 

DATR.FRM 

DATR.WFM 

DATR.FFM 

DATR.BFM 

DCOD.NUL 



FLAGS 

EQU 

EQU 

EQU 

EQU 

EQU 

EQU 

EQU 

EQU 

EQU 

EQU 

EQU 

EQU 

EQU 

EQU 



MASKS 
X'8000" 
X'4000' 
X'2000' 
X'lOOO' 
X'0800' 
X'0400' 
X'0200' 
X'OIOO' 
X'0080' 
X'0040' 
X'0020' 
X'OOIO' 
X'0008' 
X'0004' 



ATTRIBUTES MASKS 



EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
ENDS 



X'8000' 
X"4000' 
X'2000' 
X'lOOO' 
X'0800' 
X'0400' 
X'0200' 
X'OIOO' 
X'0080' 
X'0040' 
X'0020' 
X'OOIO' 
X'0008' 
X'0004' 
X'0002' 
255 



BULK DEVICE FLAG 

ON-LINE FLAG 

BISYNC BUSY FLAG 

BIT MAP PRESENCE 

PSEUDO FILEMARK CHECK 

BIT MAP MODIFY FLAG 

CONSOLE FLAG 

BISYNC DEVICE FLAG 

SVC 6 CONNECT ABLE DEVICE 

WRITE PROTECT FLAG 

HALT I/O ABORT FLAG 

FMGR CALL FROM SVC 1 FLAG 

START AT ZERO FLAG (GETSEC) 

DCB IN USE FLAG 



INTERACTIVE DEVICE 

SUPPORTS READ 

SUPPORTS WRITE 

SUPPORTS BINARY 

SUPPORTS WAIT I/O 

SUPPORTS RANDOM 

SUPPORTS UNCONDITIONAL PROCEED 

SUPPORTS IMAGE 

SUPPORTS HALT I/O 

SUPPORTS REWIND 

SUPPORTS BACKSPACE RECORD 

SUPPORTS FORWARD SPACE RECORD 

SUPPORTS WRITE FILEMARK 

SUPPORTS FORWARD SPACE FILEMARK 

SUPPORTS BACKSPACE FILEMARK 

DEVICE CODE OF NULL DEVICE 



Figure 9-2. DCB - Device Control Block 
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Maximum Record Length 

For user-written drivers, this field is zero since no device record length checking is performed. 

Read/Write Count 

This field must not be used by the driver. 

Device Code 

This field contains one of the valid user-written driver device codes (240-254) suppUed to CUP/ 16 with the DEVICE 
statement. 

Device Number 

This field contains the physical device address supplied to CUP/ 16 with the DEVICE statement. 
Attributes 
I This field contains the value X'7F7E' for user-written devices - all operations are supported except HALT I/O. 

Bit # Meaning if set 

Interactive Device 

1 Supports read 

2 Supports write 

3 Supports binary 

4 Supports wait I/O 

5 Supports random 

6 Supports unconditional proceed 

7 Supports image 

8 Supports Halt I/O 

9 Supports rewind 

10 Supports backspace record 

1 1 Supports forward space record 

1 2 Supports write file mark 

13 Supports forward space filemark 

14 Supports backspace filemark 



Keys 

This field is initially zero but may be modified by SVC 7 (Write key/Read key - 1 byte each). 
This field must not be used by the driver 

A (Busy Flag) 

This field contains a pointer to the device busy flag. 

A (Abort Termination Routine) 

This field contains the address of the stop I/O routine (UxxTRM) used by the Executive in terminating I/O in progress. 
Register conventions for the abort routine are the same as an interrupt service routine. 

Time-out Count 

This field, initially zero, may be altered by the driver if time-out service is required. The time-out count in seconds is set by 
the driver when the I/O is initiated and decremented by the clock driver. When the value is zero, the clock driver executes a 
simulate interrupt instruction on the device, notifying the driver of the device time-out. 

Flags 

This field is initially set to X"4000' indicating that the device is on-line. Other bits in the flags halfword do not apply to 
user-written devices. 
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A(Initialization Routine) 

This field contains the address of the driver initialization routine (UxxDVR). 

OldPSW 

The next locations in the DCB are: 



DBxxxx DC 0,0 OLD PSW STATUS AND LOC 

DC ISSTAT NEW STATUS 



DBxxxx is the address placed in the Interrupt Service Pointer Table. It points to an old Program Status Word save location 
where the current PSW is stored on an immediate interrupt. 



New Status 

The next location is the new status for an immediate interrupt. This status is X'3000' (ISSTAT), machine malfunction and 
fixed point divide fault interrupts enabled, all others disabled. When the immediate interrupt occurs, the Location Counter 
is forced to the next location following the new status: 



STM 


R8,I0RSAV 


LM 


R8,REG8xxxx 


BR 


RF 


STM 


R8,REG8xxxx 


LM 


R8,IORSAV 


LPSW 


DBxxxx 



SAVE INTERRUPTED REGISTERS 

LOAD ISR REGISTERS 

BRANCH TO INTERRUPT SERVICE ROUTINE 

SAVE ISR REGISTERS 

LOAD INTERRUPT REGISTERS-DCB.NOPI 

RETURN TO INTERRUPT LOCATION 



xxxx is the device mnemonic supplied to CUP/ 16 on the DEVICE statement. 

In this block of code, the registers in use at the time of the interrupt are saved in lORSAV, a common save area in the 
Executive. Eight registers must be saved, even if the interrupt service routine does not use that many. This means that the 
interrupt service routine can only use Registers 8 through 15. REGSxxxx is a location within the DCB. 

Register Save Area 

The next locations are the register save area: 



DC 





R2 


DC 





R3 


DC 





R4 


DC 





R5 


DC 





R6 


DC 





R7 


DC 





R8 


DC 





RE 


DC 





RF 



CALLER TCB POINTER AND I/O WAIT POINTER 
ADDRESS OF PARAMETER BLOCK 
FUNCTION CODE AND LU 

DEVICE NUMBER 

STATUS REGISTER, INITIALLY ZERO 



ADDR OF DCB 

ADDRESS OF INTERRUPT SERVICE ROUTINE 



It is the responsibility of the driver initialize routine to set up this area. Registers 2, 3, 4, 6, and 7 are loaded by the 
Executive, but it is up to the driver initialize routine to store them and any other registers it may load for the interrupt 
service routine. Register 1 5 is initialized by System Initialization to contain the address of DCB.NOPI. This causes 
interrupts to be ignored until Register 15 is set up by the driver initialization routine. 
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Busy Flag 

The next location in the DCB is the busy flag. For devices that share a busy flag, the user may modify A(BUSY FLAG) 
in the DCB to point to a common busy flag. This is done by modifying the output of CUP/ 16 using OS EDIT. 

If a Selector Channel (SELCH) is to be used, then A(BUSY FLAG) should be modified to point to a SELCH busy flag. The 
SELCH busy flags generated by the system are of the form FFxxBSY where xx is the device number of the SELCH. The 
following statements appear at the end of the DCB: 



ORGxxxx 



ORG 

DC 

ORG 



X"nn'*2+1SPTAB 

A(DBxxxx) 

ORGxxxx 



In these statements, X'nn' is the device number, and the ORG statement sets the Location Counter of the Assembler to the 
location in the Interrupt Service Pointer Table where the address of the DCB must be stored. The second ORG sets it back 
to its previous location. For SELCH devices, the driver itself must set up the correct slot in the Interrupt Service Pointer 
Table, i.e, STH R14,X'F0"*2+X"D0'. 

Device codes 240-254 are reserved for user-written drivers. For example, the CUP/16 statement DEVICE 240,3A,USER: 
generates the following DCB : 





EXTRN 


U40TRM,U40DVR 




ENTRY 


DBUSER 




DC 


X'0000',0,0 




DC 


X'F03A' 




DC 


X'7F7E',0 




DC 


USERBSY,0,U40TRM,0 




DC 


X'4000\U40DVR 


DBUSER 


DC 


0,0,ISSTAT 




STM 


R8,IORSAV 




LM 


R8,REG8USER 




BR 


RF 




STM 


R8,REG8USER 




LM 


R8,I0RSAV 




LPSW 


DBUSER 


REG2USER 


DC 


0,0,0,0,0,0,0 


REG8USER 


DC 


0,0,0,0,0,0,0,0 


USERBSY 


DC 


x'oo' 


ORGUSER 


ORG 


X'3A"*2+ISPTAB 




DC 


DBUSER 




ORG 


ORGUSER 



DRIVER ABORT ROUTINE AND DRIVER ADDRESS 

DCB ADDRESS 

PPSW, MAX RECORD LENGTH, READ/WRITE COUNTS 

DEVICE CODE, DEVICE NUMBER 

ATTRIBUTES, KEYS 

ADDRESS OF BUSY FLAG, TERM AND 

ABORT ROUTINES, TIMEOUT COUNT 
FLAGS, ADDRESS OF DRIVER 
OLD PSW, NEW PSW STATUS 
SAVE REGISTERS ON INTERRUPT 
LOAD DRIVER REGISTERS 
GO TO DRIVER 
SAVE DRIVER REGISTERS 
LOAD INTERRUPTED REGISTERS 
RETURN 
REGISTER SAVE AREA 

BUSY FLAG 

ORG TO ISP TABLE SLOT 

DEPOSIT DCB ADDRESS 

RE-ORG 



NOTE 

The abort and driver initialization routine addresses are always of 
the form UxxTRM and UxxDVR where xx is the device code 
(truncated to two digits) specified in the DEVICE statement. 



DRIVER LOGIC FLOW 

Figure 9-3 shows the internal flow of an I/O operation starting with the Supervisor Call instruction executed by a running 
task and ending with the return through the scheduler to activate the highest priority ready task. 
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I/O INITIALIZATION 



USER TASK 



I 



rsvc 1 interrupt;) 



SVC 1 



lOEXIT 




YES 



DRIVER 

INITIALIZATION 

ROUTINE 



1 



BUSY 



(BRANCH) 



TASK PUT INTO I/O 
WAIT FOR THE 
DEVICE (UNLESS 
UNCONDITIONAL 
PROCEED OR TEST 
I/O WAS SPECIFIED) 
UNTIL DEVICE IS 
MADE NON-BUSY BY 
lODONE 




SUSTAT 



" / ISSTATy 



SUSTAT X 7C00 

QUEUE INTERRUPT AND 
PROTECT MODE DISABLED 



ISSTAT X'SOOO' 

MACHINE MALFUNCTION AND 

FIXED PT. DIVIDE FAULT 

ENABLED 



USER SUPPLIED 
DRIVER 



V' 



) r > ) 

INTERRUPT' 
SERVICE 




Csint) 



. C LPSW DBxxxx ") 



DRIVER 

initialization 

ROUTINE 



T 



-CaRANCH) 



IOTWAT 



.(^BRANCH) 



lOTERM 



T 



-^BRANCH") 



TASK 
SCHEDULER 



"CUPSW ) 



USER TASK 



Figure 9-3. Internal Flow 
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INTERRUPT SERVICE 



I/O TERMINATION 



USER TASK 

SYSTEM TASK 

EXECUTIVE 



/I MM El DATE 
\INTERRUPT, 



DRIVER 

INTERRUPT 

SERVICE 

ROUTINE 



Clpsw) 



USER TASK 

SYSTEM TASK 

EXECUTIVE 



DRIVER 

TERMINATION 

ROUTINE 



YES 



USER TASK 

SYSTEM TASK 

EXECUTIVE 



DRIVER 
INTERRUPT 
SERVICE 
ROUTINE 



EXECUTIVE 



lOTERM 




lODONE 



lOTERM 
(QUEUE EMPTY) 



/"immediateN 

_vlNTERRUPT>^ 



I/O COMPLETED 
TERMINATION PHASE 
ENTERED WITH ATL OF 
A(DCB)+1 ON SYSTEM 
QUEUE (LIOTRM) LPSW 
WITH BIT 6 OF PSW SET. 
SYSTEM QUEUE INTERRUPT 
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-CBRANCH") 
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scheduler 
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user TASK 



Figure 9-3. Internal Flow (Continued) 
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SUPERVISOR CALLS 

All requests for I/O operations start with a Supervisor Call instruction, such as: 
SVC l.PBLK 

in which the 1 in the Rl field indicates an I/O request and PBLK in the A(X2) field is the address of a parameter block. 
The parameter block must consist of a one byte function code and a one byte logical unit number. The meaning ot bits 
within the function code is left for interpretation by the driver with the following exceptions: 

1 . Bit must signify commands/data transfer 

2. Either or Both of Bits 1 and 2 must be on for a data transfer 

3. Bit 4 must signify wait or proceed 

4. Bit 6 must be used for unconditional proceed 



The logical unit number must be less than the SYSGEN parameter UNITS. The second halfword of the parameter block 
must be reserved as a location in which the system can return ending status and the device number on completion ^^ 
operation. The entire parameter block must be within the user desingated memory area. If Bit of this function code 
specifies a data transfer, the length of data transferred (in bytes) is returned in the parameter block. See Figure 9-4 for the 
SVC 1 parameter block STRUC. 



SVCl. 


STRUC 






SVCl.FUN 


DS 





FUNCTION CODE/LOGICAL UNIT 


SVCl.FC 


DS 


1 


FUNCTION CODE 


SVCl.LU 


DS 


1 


LOGICAL UNIT 


SVCl. ST A 


DS 





STATUS 


SVCl DIS 


DS 


1 


DEVICE INDEPENDENT STATUS 


SVCl.DDS 


DS 


1 


DEVICE DEPENDENT STATUS 


SVCl. SAD 


DS 


2 


STARTING ADDRESS 


SVCl.EAD 


DS 


2 


ENDING ADDRESS 


SVCl. RAD 


DS 


4 


RANDOM ADDRESS 


SVCl.LXF 


DS 


2 


LENGTH OF LAST TRANSFER 


* 


FUNCTION CODE 




SIFC.RDM 


EQU 


X'40' 


READ 


SIFC.WRM 


EQU 


X'20' 


WRITE 


SIFC.BIM 


EQU 


X'lO' 


BINARY/ASCII 


SIFC.WTM 


EQU 


X'08' 


WAIT/PROCEED 


SIFC.RNM 


EQU 


X'04' 


RANDOM/SEQUENTIAL 


SIFC.UPM 


EQU 


X'02' 


UNCONDITIONAL PROCEED 


SIFC.IMM 


EQU 


X'or 


IMAGE/FORMATTED 


SIFC.CMM 


EQU 


X'80' 


COMMAND FUNCTION 


SIFC.RWM 


EQU 


X'40' 


REWIND 


SIFC.BRM 


EQU 


X'20' 


BACKSPACE RECORD 


SIFC.FRM 


EQU 


X'lO' 


FORWARD SPACE RECORD 


SIFC.WFM 


EQU 


X'08' 


WRITE FILE MARK 


SIFC.FFM 


EQU 


X'04' 


FORWARD FILE 


SIFC. BFM 


EQU 


X'02' 


BACKWARD FILE 


* 


STATUS HALFWORD 




SIST.ERM 


EQU 


X'8000' 


ERROR STATUS 


SI ST. IFM 


EQU 


X'4000' 


ILLEGAL FUNCTION 


SIST.DUM 


EQU 


X'2000' 


DEVICE UNAVAILABLE 


SI ST. EMM 


EQU 


X'lOOO' 


END OF MEDIUM 


SIST.EFM 


EQU 


X'0800' 


END OF FILE 


SIST.UEM 


EQU 


X'0400' 


UNRECOVERABLE ERROR 


SI ST. REM 


EQU 


X'0200' 


RECOVERABLE ERROR 


SIST.LUM 


EQU 
ENDS 


X'OIOO' 


ILLEGAL OR UNASSIGNED LU 



Figure 9-4. SVC 1 Parameter Block 
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EXECUTIVE ROUTINES 

Several Executive routines are involved in starting an I/O operation. Of prime interest to those writing drivers is the SVC 1 
handler (SVCl). This routine performs the following functions: 



1 . Save the caller's registers. 

2. Picks up the logical unit number. The logical unit number must be less than UNITS. If not, the routine 
returns illegal LU status, X'81 ', to the caller immediately. 

3. Gets the DCB address from the task's logical unit table. 

4. If the function code specifies data transfer (bit reset), it checks the function with the device 
attribute. If any part of the function is unsupported, it returns illegal function status, X'CO", to the 
caller immediately. If the function code specifies a command and there are no supported functions (as 
described in the section entitled Device Control Block) specified, it returns to the caller with 
normal status. 

5. Checks the device busy flag. If set, it puts the caller in I/O wait for the device (unless unconditional 
proceed or test I/O is specified). 

6. Sets the busy flag for all devices except the disc and a binary synchronous communication line. The 
address of the DCB is put in the busy flag. 

7. Branches to the driver. On entry to the driver, the following registers are set up; 



Rl - Address of DCB 

R2 - Caller's TCB Pointer and I/O Wait Pointer 

R3 Address of SVC 1 parameter block 

R4 - Function and logical unit 

R6 — Device number 

R7 — Zero (status register) 

R8 — Address of driver 



DRIVER INITIALIZE ROUTINE (DIR) 

The actual function of the driver initialize routine depends largely on the device. In general, the driver: 

1. Performs further checking on the function code for validity and to determine the type of operation. 

2. Sets up general registers 8-15 as follows: 

R8-13 As needed for later user by the interrupt service routine of the driver 

R14 Address of DCB 

Rl 5 Address of the interrupt service routine to be entered on the first interrupt 

3. Stores general registers 2-1 5 in the DCB at REG2 save area (DCB.RSAV). 

4. Simulates an interrupt from the device to get to the interrupt service routine where actual I/O 
instructions can be used. 

5. Returns to the Executive. 

The driver returns to the Executive at one of two locations. If all has gone well, and the interrupt service routine is 
activated, the driver returns to lOTWAT, a routine in the Executive that takes care of the I/O wait thread before exiting to 
the Task Scheduler. If the driver determines that there is something wrong with the operation before going to the interrupt 
service routine, it returns through lOEXlT. On this return, the status register R7 must return with the appropriate status, 
usually illegal operation, X'COOO'. For either return, registers 1,2,3,4, and 6 must be set up as they were on entry to the 
driver. 
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(DCB.ENTR) 


STM 




LM 




BR 


(DCB.LEAV) 


STM 


(DCB.NOPI) 


LM 




LPSW 



INTERRUPT SERVICE ROUTINE (ISR) 

The interrupt service routine, like ttie initialize routine, is very device dependent. It is activated in one of three ways: 

1 . By the initialize routine to start the device (SINT). 

2. By subsequent interrupts from the device. 

3. By a Simulate Interrupt from the system (time-out). 

Entry to the interrupt service routine is always through an interrupt, either simulated or real. The following sequence 
occurs on such an interrupt: 

1 . The current PSW is saved in the DCB old PSW save location (DCB.OPSW). 

2. The new status, ISSTAT (X'3000', machine malfunction and fixed point divide fault interrupts en- 
abled), is loaded from the new PSW status location of the DCB (DCB.NPSS). 

3. The location counter points to the next location of the DCB (DCB.ENTR) which contains the sequence: 

R8,I0RSAV 
R8,REG8xxxx 
RF 

R8,REG8xxxx 
RB.IORSAV 
I DBxxxx 

The DCB saves eight registers, starting with R8, at the location lORSAV. lORSAV is a reserved area of 16 bytes in the 
Executive. Then, eight registers are loaded from REGSxxxx, a location within the DCB register save area (DCB.RSAV+12), 
and the location in Register 1 5, as set up by the initialize routine is entered. What occurs here is device dependent. Usually, 
the interrupt service routine issues an output command to the device to get it started and sets up Register 15 for 
subsequent interrupts. Because only eight registers are saved, the ISR can only use R8-RF. References to R2-R7 can be 
made by accessing the save area corresponding to the register number in DCB.RSAV. The ISR must not execute any 
instructions other than Ust instructions, which cause software traps to be entered, (i.e., Multiply and Divide) as the traps 
run with external interrupts enabled. The interrupt service routine must exit by branching back to the DCB, either to the 
second store multiple instruction (DCB.LEAV), or to the second load multiple instruction (DCB.NOPI), depending on 
whether it has to save any registers. In the case where the interrupt service routine is started by the initialize routme, the 
load PSW instruction returns control, with external interrupts again enabled, to the initialize routine, at the instruction 
immediately following the simulate interrupt instruction. 

When the interrupt service routine is activated as a result of a subsequent interrupt from, the device, it ciiecks device status, 
performs the necessary operation, and exits through the DCB. On the final interrupt, the interrupt service routine executes 
an ATL instruction to put the address of the DCB-H on the I/O termination queue, LIOTRM, and sets up the termination 
address, (DCB. TERM), if required, before exiting through the DCB. 

I/O TERMINATION 

The system enters the I/O termination routine, lOTERM, as a result of an I/O termination queue interrupt. This interrupt 
is generated if there is something in the I/O termination queue, LIOTRM, and the processor executes a LPSW or EPSR 
instruction in which Bit 6 of the new status is set. The initialize routines, lOTWAT and lOEXIT, described previously, 
branch directly to lOTERM to avoid the overhead of an extra interrupt that would occur when the Task Scheduler 
executes a LPSW to schedule a task. 

The I/O termination queue interrupt is handled by the Executive, which saves the registers at the time of the interrupt and 
branches to lOTERM. lOTERM performs the following functions: 

1 . It removes the bottom entry from the list, LIOTRM. 

2. If the list is empty it branches to SCHED, the Task Scheduler. 

3. If the item removed is the address of DCB+1 , it picks up the address of the driver termination routine 
from DCB.TERM. 

4. It loads Registers 2 through 15 from the DCB. If the address of the driver termination routine is zero, it 
branches directly to lODONE, described below. However, if the address is non-zero, it puts the address 
of the termination routine in Register 8, and branches on Register 8. 
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When lOTERM branches to a driver termination routine, Register 1 contains the address of the DCB, Register 8 contains 
the address of the termination routine, and the remaining registers contain what was in the DCB locations from which they 
were loaded. 

Termination routines, like initiaUze and interrupt service routines are device dependent. In many cases, they are not 
required at all, i.e., the action taken by lODONE is sufficient to terminate the operation. The terminate routine can be 
used for code conversion, special error checking, or any other operations required after the transfer is complete that can be 
done with external interrupts enabled. Driver termination routines must exit by branching to lODONE. 

lODONE 

lODONE is the common termination routine in the Executive. It expects Register 1 to contain the address of the DCB, 
Register 2 to contain the caller pointer, as set up by SVC 1, Register 3 to contain the SVC 1 parameter block address. 
Register 7 to contain the device independent status. Register 6 to contain the device dependent status, and Register 10 to 
contain the A(last byte transferred)+l. lODONE returns status and length of data transfer to the caller, takes all tasks in 
the I/O wait thread for that device out of I/O wait, and clears the I/O wait thread. If the device independent status 
(contents of Register 7) is non-zero, it returns the device dependent status, contents of Register 6, to the caller along with 
the device independent status. lODONE exits through lOTERM, to remove all items from the queue, before returning to 
the Scheduler. Any tasks that were in I/O Wait for the device are now rescheduled by priority. 

I/O WAIT 

Tasks which require I/O on a device that is busy (and the function code specified neither unconditional proceed nor test 
I/O) are put on the I/O wait thread for that device (see Figure 9-5). The thread starts in the right byte of REG2xxxx in the 
DCB. Its contents are the TCB pointer of the next task in the thread. The thread continues through the TCBs of all tasks in 
the thread. The end of the thread is X'OO'. 

Register 2 is initialized by SVC 1 with the caller's TCB pointer in the left byte and X'OO' in the right byte. It must be saved 
in REG2XXXX in the DCB by the driver in the initialization phase. The thread is built by SVC 1 as other tasks require that 
device. The user written driver must maintain the integrity of REG2xxxx. If this location is overwritten the thread is 
destroyed. 



DCB FOR DEVICE xxxx 



DBxxxx 



TCB FOR 1ST TASK IN 
I/O WAIT 



TCB FOR 2ND TASK IN 
I/O WAIT 




TCB FOR LAST TASK IN 
I/O WAIT 



Figure 9-5. I/O Wait Thread 



9-12 



29429 R02 7/76 



CANCEL I/O 

When a task is cancelled, either by a console CANCEL or an SVC 6 task cancel, or goes to End of Task (SVC 3), and I/O is 
on-going for that task, the EOT routine gets the DCB driver abort routine address (DCB.ALOC). It stores it in the Register 
15 save area in the DCB (DCB.ISR), and executes a simulate interrupt instruction (SINT). The abort routine is entered in 
ISSTAT state, (X'3000') with the registers initiahzed from REGSxxxx (save area in DCB). The logic of the driver abort 
routine depends largely on the device, but it generally issues a STOP I/O command to the device, sets an unrecoverable 
error, schedules the I/O termination routine (ATL to LIOTRM), and exits via the DCB (DCB.LEAV). 

HALT I/O 

When a task requests Halt I/O to a device that supports it, and I/O is on-going, the driver's abort routine is entered, as if the 
task was cancelled, except that the Halt I/O flag (DFLG.HIM) is set in DCB.FLGS. If the abort routine finds this flag set, it 
returns Halt I/O error status (X'8281 ') instead of an unrecoverable error status. 



SAMPLE DRIVER 

The following driver is similar to the standard OS/16 MT2 Card Reader Driver. It is presented as a coding sample for user 
written drivers. The comments on the listing reflect the functions described in the previous narrative. 



THIS PROGRAM IS A CARD READER DRIVER. 

IT READS UP TO 80 ASCII CHARACTERS 

OR 160 IMAGE CHARACTTERS 

IT CONVERTS THE HOLLERITH DATA 

PRODUCED BY AN IBM029 OR 

IBM 026 KEYPUNCH. 

EXTRN/ENTRY DECLARATIONS: 

EXTRN LIOTRM,IOTWAT,IODONE, lOEXIT 

ENTRY CRDDVR.CRDTRM 



* 
CRISR 



REGISTER ALLOCATION 
COPY REGS 
COPY DCB 
COPY SVCl. 



HOLBUF 


EQU 


DCB.SDN 


* 


ENTERED HERE ON SVC IF : 


* 


INITIALIZATION PHASE 


CRDDVR 


LBR 


RD,R6 




SSR 


RD,RO 




THI 


R0,X'20' 




BZS 


CRDVRB 




LHI 


R7,X'AO00' 


H: 


B 


lOEXIT . 


CRDVRB 


LHI 


RA,HOLBUF(Rl) 




LIS 


RB,2 




LHR 


RE,R1 




LHI 


R8,CRTERM 




STH 


R8,DCB.TERM(RE) 




LHI 


RC,159(RA) 




LHI 


RF,CRISR 




STM 


R2,DCB.RSAV(R1) 




SINT 


0(RD) 




B 


lOTWAT 



MOVE DEVICE NUMBER TO RD 

SENSE STATUS 

IS HOPPER EMPTY? 

NO: READ A CARD 

HOOPER EMPTY = D. U. 



SET STARTING ADRS OF BUFF 

SET BXH INCREMENT VALUE 

ADRS OF DCB INTO R14 

SET UP TERMINATION ROUTINE ADDRESS 

SET END ADRS OF CARD BUFF 

SET INTERRUPT SERVICE ROUTINE ADDR 

SAVE DRIVER REGISTERS 

START I/O OPERATION 

EXIT INITIALIZATION PHASE 

ON I/O INTERRUPT CONTROL TRANSFERS HERE, INTS DISABLED. 

INTERRUPTS SERVICE ROUTINE PHASE 

LHI RF,CRISR1 SET ISR POINTER 

OC RD,CFEED FEED A CARD 

B DCB.LEAV(RE) RETURN AND WAIT FOR FIRST INT 
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CRISRl SSR RD,R8 

BFC 1 ,NOTDU 

CRDTRM EQU * 

ERR LHI RB,X'8400' 

STH RB,DCB.RSAV+10(RE) 

XHR R8,R8 

STH R8,DCB.TERM(RE) 

BACK OC RD.DISABL 

LHI RF.DCB.NOPKRE) 

AIS RE,1 

ATL RE.LIOTRM 

B DCB.LEAV-l(RE) 

NOTDU BNOS CHKSTS 

THI R8,X"D0' 

BNZ ERR 

CHKSTS SSR RD,R8 

NHI R8,X'20' 

BZ ERR 

BSY SSR RD,R8 

BSY2 BTC 8,DCB,NOPl(RE) 

RH RD,0(RA) 

BXH RA.BACK 

SAVE STH RA,DCB.RSAV+16(RE) 

B DCB.NOPI(RE) 



CHECK STATUS 

BRANCH IF DEVICE AVAILABLE 

(THE ABORT ROUTINE IS HERE) 

UNREC ERROR STATUS 

SAVE IT IN R7 SAVE AREA 

lODONE RETURN 

ZERO TERMINATION ROUTINE ADDR 

DISABLE INTERRUPTS 

SET NOP ISR 

MAKE DCB ADRS ODD 

RETURN 

EXAMINE SET? 

ANY BAD STATUS? 

YES 

GET STATUS SOON 

YES: HOPPER EMPTY SET? 

NO: UNREC ERR 

GET STATUS AGAIN 

BSY=1? 

READ 2 BYTES 

LOOP FOR ENTIRE CARD 

SAVE CURRENT BUFFER POINTER ONLY 

RETURN 



CFEED 


DB 


X'60' 


DISABL 


DB 


X'80' 


* 


TERMINATION ROUTINE 


CRTERM 


LH 


R8,SVC1.SAD(R3) 




LIS 


R9,l 




LH 


RA,SVC1.EAD(R3) 




LHI 


RC,H0LBUF(R1) 




THI 


R4,X'0I00' 




BZS 


CRASCI 



FEED A CARD 
DISABLE INTS 
CONVERT CARD 

GET USER BUFFER START ADDR 
SET BXLE LOOP 
GET USER BUFFER END ADDR 
GET DRIVER BUFFER ADDR 
ASCII OR IMAGE 

* HERE MOVE DATA DIRECTLY FROM DRIVER BUFFER TO USER BUFFER 
B LENGTH 

CRASCI EQU * 

* HERE CONVERT EACH HOLLERITH HALFWORD 

* TO AN ASCII BYTE AND STORE IN USER BUFFER 

LENGTH LHR RA,R8 RA=A(LAST BYTE TRANSFERRED)+1 

USED BY lODONE TO CALCULATE 
LENGTH OF XFER 
B lODONE END TERMINATION PHASE 



This sample driver can be assembled with the following sequence of commands, assuming the source is on cards: 



LD 


CAL16 


TA 


.BG 


AL 


CRDDVR.OBJJN 


AL 


SCRAT,IN,80 


AL 


CROSS,IN,256 


AS 


I,CR: 


AS 


2,CRDDVR.OBJ 


AS 


3,PR: 


AS 


4,SCRAT 


AS 


5, CROSS 


AS 


7,PCBI6.CAL 



START 



;* ALLOCATE OBJECT FILE 
;* ALLOCATE SCRATCH FILE 
;* ALLOCATE CROSS FILE 
;* ASSIGN INPUT DEVICE 
;* ASSIGN OUTPUT FILE 
;* ASSIGN LIST DEVICE 
;* ASSIGN SCRATCH FILE 
;* ASSIGN CROSS FILE 
;* ASSIGN COPY FILE 
;*STARTCAL16 
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SUMMARY OF REGISTER CONVENTIONS 

Registers On Entry To Driver 

The driver is entered witli the following registers set up: 

Driver Initialization Routine 

Rl = A(DCB) 

R2 = caller TCB pointer, left byte 

X'OO' right byte 
R3 = A(SVC1 parameter block) 
R4 = Function Code, left byte 

Logical Unit, right byte 
R6 = Device Number 
R7 = Status 
R8 = A(Driver initiaUzation routine) 

Driver Interrupt Service Routine and Abort Routine 

R8-R15 initiahzed with REGSxxxx (save area in DCB) 
Driver Termination Routine 

R2-R15 initiahzed with REG2xxxx (save area in DCB) 

Registers On Entry To Executive 

The driver must insure the following registers are set up before branching to the Executive entry points. 



Rl = 


A(DCB) 


R2 = 


caller TCB pointer, left byte 




X'OO', right byte 


R3 = 


A(SVC1 parameter block) 


R4 = 


Function code, left byte 




Logical unit, right byte 


R6 = 


Device number 


R7 = 


status 



lOEXIT 

Same as lOTWAT except for 
R6 = device dependent status 
R7 = device independent status 



lODONE 

Rl = A(DCB) 

R2 = caller TCB pointer, left byte 

I/O wait pointer, right byte 
R3 = A(SVC 1 parameter block) 
R6 = device dependent status 
R7 = device independent status 
R10= Adast byte transferred)+l 

used only on data transfer requests 
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RTOS DRIVER COMPATIBILITY WITH OS/16 MT2 

The following is a list of items for consideration when converting an existing RTOS driver for user under OS/ 1 6 MT2 : 

1. The names of the Driver Initialize Routine and the Driver Abort Routine must be of the form 
xxxDVR and xxxTRM. 

2. The abort routine must be modified to return an unrecoverable error for recovery from a power 
failure. 

3. The abort routine may be modified to support Halt I/O, if desired. 

4. Branching to DCB.LEAV always saves R8-RF. If fewer registers are to be saved, the ISR must save 
them itsel f and exit to DCB . NOPI . 

5. When lODONE is entered, RA must contain the address of the last byte transferred plus one, or the 
SVCl.LXF field will not be set up properly. 

WRITING DRIVERS FOR EXTENDED MEMORY SYSTEMS 

The following items should be considered when writing drivers for an extended memory processor: 

1 . The start and end addresses of the SVC 1 parameter block, or any other user program addresses 
processed by the driver, must be mapped by the driver during the driver initialization phase, then 
stored in the DCB Register Save area. 

2. Location DCB.NPSS+1 must be set up with the correct PSW bits 8-1 1 so that the ISR portion of 
the driver can reference extended memory via the mapped start and end addresses. 



Example: LH RA,SVC1.SAD(R3) 
LH RB,SVC1.EAD(R3) 
IFNZ EXT 
SETM RA,SVCPSW 
SETM RB,SVCPSW 
EPSR R9,R9 

STB R9,DCB.NPSS+1(RE) 
ENDC 



GET START ADDRESS 

GET END ADDRESS 

IF EXTENDED MEMORY SYSTEM 

MAP THEM 

GET PSW 

SET UP ISR TO TALK 

TO USER PROGRAM BUFFER 



3. When programming a selector channel (SELCH) on extended memory systems, it must be noted 
that the SELCH requires extended memory addresses in a modular 64KB form with the extended 
memory bits in bits 6 and 7 of the SELCH Output command (OC). The driver must convert these 
addresses and calculate the OC values. 



Example: LH R5,SVC1.SAD(R3) 

LH R6,SVC1.EAD(R3) 

IFNZ EXT 

EPSR RO,RO 

STB R0,DCB.NPSS+1(RE) 

LBR RO.RO 

LHR R5,R5 

BMS ABOVE 32 

XHR RO,RO 
ABOVE 32 AHIR0,X'10' 

BCS UP64KB 
NHI R5, X'7FFF 
NHI R6, X'TFFF' 
UP64KB EQU * 
ENDC 



GET START ADDRESS 

GET END ADDRESS 

IF EXTENDED MEMORY SYSTEM 

GET PSW 

SET UP ISR PSW TO TALK TO USER BUFFER 

CLEAR BIT6 0-7 

IS BUFFER IN LOWER 32KB? 



CLEAR PSW 

DIVIDE BITS 8-1 1 BY t 

AND MOVE TO BITS 13-15 (ROUND-UP) 

IF CARRY THEN IT'S IN UPPER 32KB OF A 

64KB MODULE. 

IF NOT, KILL BIT OF ADDRESS 



RO(BITS 14-15) HAS 

CORRECT BITS 6 AND 7 

OR SELCH OUTPUT COMMAND. 
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APPENDIX 1 
SVC SUMMARY 



General form of an SVC instruction is: 

SVC N, P 

N - Particular SVC number 

P - Effective address of parameter block or parameter 

SVC parameter blocks must be aligned on a halfword boundary. 



Function 

I/O Requests 

Task Control 
Pause self 
End self 

Load another foreground task 
Start another foreground task 
Cancel another foreground task 
Send a message to another task 

Add parameter to another foreground task's Task Queue 
Add parameter to own Task Queue 
Change another foreground task's priority 
Change own priority 
Connect Trap Generating Device to task 
Enable Trap Generating Device for interrupts 
Disable Trap Generating Device interrupts 
Cause a Trap Generating Device interrupt 
Disconnect Trap Generating Device from task 
Delete task from memory 
Make task memory resident 
Load and Start task 
Find Task Status 
Find Task priority (current) 
Find Task ID of self 
Find Task options of self 
Find Current TSW for self 
Find UDL 
Enable traps 

Enable Task Queue entries 
Disable Task Queue entries 
Wait for trap 

Memory Management 

Get storage from allocated memory 
Return gotten storage to allocated memory 
Find memory limits for task 
Fetch overlay into memory 

Utility Functions 

Output message to system console 
Convert from ASCII Hexadecimal to Binary 
Convert from ASCII Decimal to Binary 
Convert from Binary to ASCII Hexadecimal 
Convert from Binary to ASCII Decimal 
Convert ASCII File Descriptor to SVC 7 format 
Search for occurrence of ASCII String in a table 
Move ASCII characters up to some ending character 
Change PSW Condition Code 
Disable or Enable Arithmetic Faults 



SVC 
SVCl 



SVC 2 
SVC 3 
SVC 6 
SVC 6 

SVC 6 
SVC 6 
SVC 6 
SVC 6 
SVC 6 
SVC 6 
SVC 6 
SVC 6 
SVC 6 
SVC 6 
SVC 6 
SVC 6 
SVC 6 
SVC 6 
SVC 6 
SVC 2 
SVC 2 
SVC 2 
SVC 2 
SVC 9 
SVC 9 
SVC 9 
SVC 9 



SVC 2 Code 2 
SVC 2 Code 3 
SVC 2 Code 5 
SVC 5 



SVC 2 Code 7 
SVC 2 Code 1 5 
SVC 2 Code 15 
SVC 2 Code 6 
SVC 2 Code 6 
SVC 2 Code 16 
SVC 2 Code 17 
SVC 2 Code 18 
SVC 2 Code 4 
SVC 2 Code 4 



Code 1 

or SVC 6 End Task 

Load 

Start 

End task 

Send Message 

Queue parametei 

Queue parameter 

Change priority 

Change priority 

Connect 

Thaw 

Freeze 

SINT 

Unconnect 

Task Non Resident and End task 

Task Resident 

Load and Start 

no function 

no function 

Code 19 

Code 19 

Code 19 

Code 5 
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Clock Services 

Fetch Date (ASCII) 

Fetch Time (ASCII or Binary) 

Wait for specified time of day 

Wait for specified number of milhseconds 

Take a trap at specified time of day 

Take a trap in specified number of milliseconds 

Cancel a time trap 



File Management 

Allocate a direct access file on a device 
Assign a device/file to a Logical Unit 
Deassign a Logical Unit 
Delete a direct access file from a volume 
Change the protection keys of a file 
Change the name of a direct access file 
Change the name of a device (E-task only) 
Delete an unconditionally protected file 

(Keys of FF) (F.-task only) 
Flush output buffers of buffered file or device 
Find the maximum record length of device/file 

assigned to a Logical Unit 
Find File Descriptor of device/file assigned to 

a Logical Unit 
Append Data to Indexed File 
Find Number of Logical Units available to task 



SVC 2 Code 9 




SVC 2 Code 8 




SVC 2 Code 23 




SVC 2 Code 23 




SVC 2 Code 23 




SVC 2 Code 23 




SVC 2 Code 23 




SVC 7 Allocate 




SVC 7 Assign 




SVC 7 Close 




SVC 7 Delete 




SVC 7 Assign, Reprotect, and Close 


SVC 7 Assign, Rename, 


and Close 


SVC 7 Assign, Rename, 


and Close 


SVC 7 Delete 





SVC 7 Checkpoint 
SVC 7 Fetch Attributes 

SVC 7 Fetch Attributes 

SVC 7 Assign for EWO or SWO 
SVC 2 Code 19 





SVC 1 INPUT/OUTPUT REQUEST 






CAL CODE 






ALIGN 


2 


PARBLK 


DB 


fc,lu 




DC 


H'O' 




DAC 


START 




DAC 


END 




DC 


Y'random' 




DAS 


1 




DC 


Y'EXTOPT' (IT AM 0^ 


JLY) 



FORMAT 



0(0) 


FC 


1(1) 

LU 


2(2) 


STATUS 


4(4) 


A(START) 


6(6) 


A(END) 


8(8) 


RANDOM 


12(C) 


LENGTH OF XFR 


14(E) 


(4 bytes) 
EXT.OPT. (ITAM) 



CONDITION CODE 

NORMAL COMPLETION 

F (ALL BITS) UNCONDITIONAL PROCEED REQUEST FOR BUSY FILE/DEVICE. 
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SVC 2 CODE 1 - PAUSE 



PARBLK 



CAL CODE 

ALIGN 2 
DB 0,1 



NO OPTIONS SUPPORTED 
CONDITION CODE UNCHANGED. 



APPENDIX 1 (Continued) 



Zl 



FORMAT 



0(0) 



00 



1(1) 
1(01) 



I SVC 2 CODE 2 - GET STORAGE [ 



PARBLK 



CAL CODE 

ALIGN 2 
DB OPTION,2 
DC H'REG' 
DAC SIZE 



FORMAT 



, 


0(0) 

OPTION 


1(1) 
2(02) 


2(2) 

REG 


4(4) 

SIZE 



OPTIONS 

X'OO' - 
X'80' - 



MEANING 

GET NUMBER OF BYTES SPECIFIED BY SIZE 

GET ALL ALLOCATED MEMORY - NUMBER OF BYTES OBTAINED 

IS RETURNED IN SIZE 



REG - SPECIFIES GENERAL REGISTER USED TO RETURN STARTING ADDRESS OF 
REQUESTED MEMORY. 

CONDITION COD E 

- NORMAL COMPLETION „^-^^^,r.„^ 

4(V-BIT) - REQUESTED SIZE TOO LARGE OR NEGATIVE. REG SET TO ZERO. 
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SVC 2 CODE 3 - RELEASE STORAGE 



PARBLK 



CAL CODE 

ALIGN 2 
DB 0,3 
DAC SIZE 



NO OPTIONS 

CONDITION CODE 



4 (V-BIT) 



0(0) 



2(2) 



FORMAT 



00 



1(1) 
3(03) 



SIZE 



MEANING 

NORMAL COMPLETION 

SIZE TOO LARGE OR NEGATIVE 



SVC 2 CODE 4 - SET STATUS 



PARBLK 



CAL CODE 

ALIGN 2 

DB 0PTI0N,4 

DB AF.CC 



OPTION (HEX) 

00 
80 

AF BYTE (HEX) 

00 
10 
04 

14 



CC BYTE (HEX) 

Ox 
CONDITION CODE 
VALUE SPECIFIED IN CC BYTE. 



FORMAT 



0(0) 

OPTION 


1(1) 

04(04) 


2(2) 

AF 


3(3) 

CC 



MEANING 

MODIFY STATUS AND CONDITION CODE 
MODIFY CONDITION CODE ONLY 

MEANING 

DISABLE ARITHMETIC FAULTS 
ENABLE FIXED POINT DIVIDE FAULT ONLY 
ENABLE FLOATING POINT ARITHMETIC FAULT 
ENABLE FIXED POINT DIVIDE AND 
FLOATING POINT ARITHMETIC FAULTS 

MEANING 



X IS TO REPLACE CONDITION CODE 
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SVC 2 CODE 5 ^ FETCH POINTER 



PARBLK 



CAL CODE 

ALIGN 2 
DB 0,5 

DC H'REG' 



NO OPTIONS 

CONDITION CODE 

UNCHANGED 





FORMAT 




0(0) 


00 


1(1) 


5(05) 


2(2) 


REG 





SVC 2 CODE 6 - UNPACK BINARY NUMBER 



3 



PARBLK 



CAL CODE 

ALIGN 2 

DB OPTION+N,( 

DAC DEST 



00 
20 
40 
60 
80 
CO 



FORMAT 


0(0 
OPTION+N 


1(1) 

6(06) 


2(2) 

A(DEST) 



OPTION (HEX) MEANING 



CONVERT TO HEXADECIMAL 

CONVERT TO HEXADECIMAL, EXTENDED PRECISION 

CONVERT TO HEXADECIMAL, SUPPRESS LEADING ZEROS 

CONVERT TO HEXADECIMAL, EXTENDED PRECISION, SUPPRESS LEADING ZEROS 

CONVERT TO DECIMAL 

CONVERT TO DECIMAL, SUPPRESS LEADING ZEROS 



N - LENGTH OF DESTINATION IN BYTES; IF ZERO, 4 IS ASSUMED. 

NUMBER TO BE CONVERTED IS PASSED IN GENERAL REGISTER ZERO (GENERAL REGISTERS ZERO 
AND ONE FOR EXTENDED PRECISION). 



CONDITION CODE 
UNCHANGED 
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SVC 2 CODE 7 - LOG MESSAGE 



PARBLK 



CAL CODE 

ALIGN 2 
DB 



DC 
DC 



PARBLK 



OPTIONS (HEX) 

00 
40 
80 
CO 

CONDITION CODE 

UNCHANGED 



OPTION,? 
H 'LENGTH' 
C'TEXT' 



(a) 
Dl RECT TEXT 



ALIGN 


2 




DB 


OPTION,? 




DC 


H'LENGTH' 


(b) 


DAC 


TEXT 


INDIRECT TEXT 



FORMAT 



MEANING 

DIRECT TEXT, FORMATTED 
INDIRECT TEXT, FORMATTED 
DIRECT TEXT, IMAGE 
INDIRECT TEXT, IMAGE 



0(0) 

OPTION 


1(1) 


7(0?) 


2(2) 

LENGTH 


4(4) 

TEXT 




0(0) 

OPTION 


1(1) 


7(0?) 


2(2) 

LENGTH 


4(4) 

A(TEXT) 



SVC 2 CODE 8 - FETCH TIME 



CAL CODE 

ALIGN 2 
PARBLK DB OPTION,: 

DAC DEST 



OPTIONS (HEX) 

00 
80 

CONDITION CODE 

UNCHANGED 



FORMAT 



0(0) 



OPTION 



1(1) 



2(2) 



A(DEST) 



8(08) 



MEANING 

ASCII FORMAT (hh:mm:ss) 

BINARY FORMAT (4 BYTES -SECONDS SINCE MIDNIGHT) 
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SVC 2 CODE 9 - FETCH DATE 



3 



PARBLK 



CAL CODE 

ALIGN 2 
DB 0,9 

DAC DEST 



FORMAT 


0(0) 

00 


1(1) 

9(09) 


2(2) 

A(DEST) 



NO OPTIONS - DATE RETURNED IN ASCII mm/dd/yy (or dd/mm/yy according to SYSGEN) 
CONDITION CODE 
UNCHANGED 



SVC 2 CODE 15 - PACK NUMERIC DATA 



D 



PARBLK 



CAL CODE 

ALIGN 2 

DB OPTION, 15 

DC H'REG' 



OPTIONS (HEX) 

00 
20 
40 
60 
80 
CO 



FORMAT 



0(0) 



OPTION 



1(1) 



2(2) 



REG 



1 5(0F) 



MEANING 

HEXADECIMAL 

HEXADECIMAL, EXTENDED PRECISION 

HEXADECIMAL, SKIP LEADING BLANKS 

HEXADECIMAL, EXTENDED PRECISION, SKIP LEADING BLANKS 

DECIMAL 

DECIMAL, SKIP LEADING BLANKS 



BINARY RESULT RETURNED IN GENERAL REGISTER ZERO (GENERAL REGISTER ZERO 
AND ONE FOR EXTENDED PRECISION). 

RFG - SPECIFIES GENERAL REGISTER CONTAINING ADDRESS OF ASCII STRING TO 
BECONVERTEa^^^^ POINTING TO FIRST BYTE NOT CONVERTED. 



CONDITION CODE 



1 (L-BIT) 

4 (V-BIT) 



MEANING 

NORMAL COMPLETION 

NO CHARACTERS PROCESSED; GENERAL REGISTER ZERO 
SET TO ZERO. 

OVERFl OW. MORE THAN 4 HEXADECIMAL DIGITS OR 
DECIMAL GREATER THAN 216-1 (65,535) RESULT 
IS VALUE MODULO 10000 (HEX) OR 2' 6 (DECIMAL) 
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SVC 2 CODE 16 - PACK FILE DESCRIPTOR 



PARBLK 



CAL CODE 

ALIGN 2 

DB OPTION, 16 

DC H'REG' 

DAC DEST 



OPTIONS (HEX) 

00 
40 
80 
CO 



FORMAT 



0(0) 


1(1) 


OPTION 


16(10) 


2(2) 


REG 


4(4) 


A(DEST) 



MEANING 

DEFAULT SYSTEM VOLUME 

DEFAULT SYSTEM VOLUME, SKIP LEADING BLANKS 

NO DEFAULT VOLUME 

NO DEFAULT VOLUME, SKIP LEADING BLANKS 



RESULT FORMAT 



0(0) 


VOLUME NAME 


4(4) 


FILENAME 


12(C) 


EXTENSION 


15(F) 

BLANK (X'20') 



REG = SPECIFIES GENERAL REGISTER POINTING TO ASCII STRING TO BE CONVERTED. 
RETURNED POINTING TO FIRST BYTE NOT CONVERTED. 



CONDITION CODE 



1 (L-BIT) 

4 (V-BIT) 

8 (C-BIT) 

9 (L & C BITS) 



MEANING 

NORMAL COMPLETION 

NO VOLUME NAME PRESENT IN INPUT 

SYNTAX ERROR 

NO EXTENSION PRESENT IN INPUT 

NO VOLUME, NO EXTENSION IN INPUT 
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SVC 2 CODE 1 7 ~- MNEMONIC TABLE SCAN 



PARBLK 



CAL CODE 

ALIGN 2 

DB 0,17 

DB REG1,REG2 

DAC TABLE 





FORMAT 




0(0) 


00 


1(1) 


17(11) 


2(2) 


REGl 


3(3) 


REG2 


4(4) 


A(TAB1>E) 





NO OPTIONS 

REGl - SPECIFIES GENERAL REGISTER POINTING TO ASCII STRING TO BE SOURCE SCANNED. 
RETURNED POINTING TO FIRST BYTE NOT IN MNEMONIC. 

REG2 - SPECIFIES GENERAL REGISTER USED TO RETURN INDEX OF MATCHED MNEMONIC 
FROM TO NUMBER OF MNEMONICS - 1. -1 INDICATES NO MATCH. 

TART F A TART F OF ASCII MNEMONICS SEPARATED FROM EACH OTHER BY A BYTE OF 

''zero REQUIRED cZScTERS FOR EACH MNEMONIC ARE INDICATED BY SETTING 
HIGH ORDER BIT. TABLE TERMINATED WITH TWO CONSECUTIVE BYTES OF ZERO. 



CONDITION CODE MEANING 

NORMAL COMPLETION 

4 ( V-BIT) NO MATCH FOUND ; REG2 SET TO - 


1 














SVC 2 CODE 18 - MOVE ASCII CHARACTERS 








CAL CODE 




FORMAT 




ALIGN 2 
PARBLK DB OPTION + N, 18 
DB REGl REG2 


0(0) 
OPTION+N 


1(1) 

18(12) 




DAC ECSTRING 


2(2) 

REGl 


3(3) 

REG2 






4(4) 

A(ECSTRING) 




OPTIONS (HEX) MEANING 









00 
80 



NO ENDING CHARACTERS 

USE ENDING CHARACTER STRING TO TERMINATE 



N - MAXIMUM NUMBER OF CHARACTERS TO MOVE 

REGl - SPECIFIES GENERAL REGISTER POINTING TO ASCII STRING TO BE MOVED. 
RETURNED POINTING TO FIRST BYTE NOT MOVED. 

REG2 - SPECIFIES GENERAL REGISTER POINTING TO DESTINATION. RETURNED POINTING 
TO BYTE FOLLOWING LAST BYTE MOVED INTO DESTINATION. 

ECSTRING - STRING OF TERMINATION CHARACTERS OF FORM' 

1 ™+i 



M 



ENDING CHARACTERS 



3 



M - NUMBER OF ENDING CHARACTERS 
CONDITION CODE MEANING 





4 (V-BIT) 

29-429 R02 7/76 



NORMAL COMPLETION 

NO ENDING CHARACTER FOUND (OPTION X'80') 
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SVC 2 CODE 19 -PEEK 



PARBLK 



CAL CODE 

ALIGN 2 
DB 0,19 

DS 24 



FORMAT 



0(0) 

00 


1(1) 

19(13) 


2(2) 

NLU 


3(3) 

MPRI 


4(4) 

OS ID 


12(C) 

TASK ID 


20(14) 

CTSW 


22(16) 

TASK OPTIONS 


24(18) 

TASK STATUS 



NO OPTIONS 

FIELDS RETURNED: 

NLU 
MPRI 
OS/ID 

TASK ID - 
CTSW 

TASK 

OPTIONS - 
TASK 

STATUS - 

CONDITION CODE 
UNCHANGED 



NUMBER OF LUs AVAILABLE TO TASK 
MAXIMUM PRIORITY OF TASK 

ASCII ID OF OS-OS 16MT2r WHERE r INDICATES REVISION LEVEL 
EIGHT-CHARACTER ASCII TASK ID 

STATUS PORTION (FIRST 16 BITS) OF TASK'S CURRENT 
TASK STATUS WORD 

OPTIONS HALFWORD FROM TASK CONTROL BLOCK 

STATUS HALFWORD FROM TASK CONTROL BLOCK 
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SVC 2 CODE 23 - TIMER MANAGEMENT | 



PARBLK 



CAL CODE 

ALIGN 
DB 
DC 
DC 



FORMAT 



OPTION,23 

H'REG' 

Y'TIME' 



0(0) 

OPTION 


1(1) 

23(17) 


2(2) 


REG 


4(4) 


TIME 



OPTIONS (HEX) 

80 
00 



10 



MEANING 

WAIT FOR INTERVAL COMPLETION 

PROCEED AND ADD PARAMETER TO TASK QUEUE ON INTERVAL 

COMPLETION 
CANCEL TIME INTERVAL 



RFG ~ SPECIFIES GENERAL REGISTER CONTAIN PARAMETER TO BE ADDED TO 
TASK QUEUE ON COMPLETION OF INTERVAL (OPTION X 00 ^ 



TIME- BITS 



0-3 



4-31 



MEANING 

0000 - SECONDS SINCE MIDNIGHT (TIME OF DAY INTERVAL) 

0001 - MILLISECONDS FROM NOW (ELAPSED TIME INTERVAL) 
OTHER - ILLEGAL 

NUMBER OF CLOCK TICKS IN INTERVAL 

TICK = 1 SECOND FOR TIME OF DAY INTERVAL 

1 MILLISECOND FOR ELAPSED TIME INTERVAL 

(OPTIONS X'OO'AND X"80') 



CONDITION CODE 

UNCHANGED 


4(V-BIT) 



FOR OPTIONS X'OO'AND X'80' 

FOR OPTION X 10' IF SUCCESSFUL _^,^,^ 
FOR OPTION X'lO" IF NO INTERVAL FOUND 



SVC 3 - END OF TASK (EOT) 



3 



SVC 3,N 

NO PARAMETER B1.0CK; SVC EFFECTIVE ADDRESS FIELD (N) STORED IN TASK'S RETURN CODE. 
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SVC 5 FETCH OVERLAY 










CAL CODE 
A I ir.M 2 




FORMAT 


K DC 
DS 
DS 
DB 
DC 


C'OVLYNM' 

2 

1 

OPTION 

H'LU' 

MEANING 


0(0) 


OVERLAY 

NAME 
(6 BYTES) 




6(6) 


RESERVED 




8(8) 

STATUS 


9(9) 
OPTION 




10(A) 


LU 


OPTIONS (HEX) 









01 
04 



LOAD FROM SPECIFIED LU WITHOUT POSITIONING 
LOAD FROM SPECIFIED LU AFTER REWIND 



STATUS (HEX) 



MEANING 



00 
10 
20 
40 



NORMAL COMPLETION 

LOAD FAILED 

MISMATCH ON OVERLAY NAME 

OVERLAY WOULD NOT FIT IN ALLOCATED MEMORY 



CONDITION CODE 



UNCHANGED 
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SVC 6 - INTERTASK COORDINATION 



PARBLK 



CAL CODE 


ALIGN 


2 


DC 


C'TASKID' 


DC 


Y'FUNCTION' 


DS 


4 


DB 


LU 


DB 


PRI 


DS 


2 


DC 


A(START) 


DC 


Y'TIME' 


DC 


C'DEVM' 


DC 


X'PARM' 


DC 


A(MESSAGE) 


DS 


4 



FORMAT 



0(0) 



TASK ID 



8(8) 



12(C) 



FUNCTION CODE 



TASK STATUS 



14(E) 



ERROR STATUS 



16(10) 



LOAD LU 



18(12) 



RPRI 



17(11) 



PRIORITY 



19(13) 



RESERVED 



20(14) 



START ADDRESS 



22(16) 
TT DELAY TIME 



26(1 A) 



DEVICE MNEMONIC 



30(1E) 



PARAMETER 



32(20) 



MESSAGE BUFFER ADDRESS 



34(22) 



RESERVED (4 BYTES) 
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SVCl Function Codes 
Function Code - Data Transfer Request 
Bit Alignment 




1-2 



APPENDIX 1 (Continued) 



Meaning 

This bit must be ZERO to indicate a data transfer request. 

Read-Write bits. The meaning of these two bits is modified by Bits 3-7 to 
control the transfer. Basically the values are: 

10 - Read request 
01 - Write request 

1 1 - Test and Set request f&ee Chapter 8) 
00 - Wait Only or Test I/O Complete 

ASCII/RINARY bit. This bit indicates the type of formatting requested if 
Bit 7 is reset. 

- indicates ASCII formatting 

1 - indicates Binary formatting 

If Bit 7 is reset, this bit must be ZERO. 

PROCEED/WAIT bit. This bit indicates the action to be taken after the I/O 
has been initiated. 

- Proceed. Indicates that control is to be returned to the task after 

initiation of I/O. 

1 - Wait. Indicates that the task is to be put into I/O Wait until the 

data transfer is complete. 

SEQUENTIAL/RANDOM bit. 

- Sequential. Indicates the next logical record is to be accessed. 

1 - Random. Indicates the logical record specified by the RANDOM 

field is to be accessed. 

UNCONDITIONAL PROCEED bit. 

- indicates the task is to be put into I/O wait until the requested 

device/file is free. At that time the request is processed. 

1 - indicates that the request is to be rejected with a condition code 

of X'F' if the requested device/file is not free. 

FORMATTED/IMAGE bit. 

- indicates that the request is to be formatted according to the 

device/file and the setting of Bit 3. 

1 - indicates that no formatting is to be performed (Image mode). 



Function Code — Command Function Request 



Bit 



1 

2 
3 
4 
5 
6 
7 



Alignment 



Meaning 

This bit must be set to indicate a command function request. 

This bit alone set requests Halt I/O. 

Rewind 

Backspace Record 

Forward Space Record 

Write File Mark 

Forward Space File 

Backspace File 

Reserved for driver dependent functions 
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Error Status Definition (SVC 1 » 



Bit 




1 

2 
3 
4 
5 
6 
7 



Meaning if set to 1 



Always 1 for error status 
Illegal Function 
Device Unavailable 
End of Medium 
End of File 
Unrecoverable Error 
Parity or Recoverable Error 
Illegal or Unassigned LU 



Binary 



Hexadecimal 



1100 0000 


x'co' 


1010 0000 


x'ao' 


1001 0000 


X'90' 


1000 1000 


X'88' 


1000 0100 


X'84' 


1000 0010 


X'82' 


1000 0001 


X'8l' 



SVC 6 Parameter Block Fields 



Byte 


Name 


0-7 


Task ID 


8-11 


Function Code 


12-13 


Task Status 


14-15 


Error Status 


16 


Load LU 


17 


Priority 



19 
20-21 



22 
(Bits 0-3) 



26-29 



30-31 



32-33 



RPRI 



Start Address 



TT 



22-25 Delay Time 

(Bits 54-31) 



Device Mnemonic 



Parameter 



Meaning 



A(message) 



Name of task; not required if call is self-directed. 
Specifies desired functions. 

The wait status halfword of the specified task is returned by the system in 
this field. 

Set to ZERO for normal termination or to error code if error detected. 

Specifies LU from which to load the task. Used only for Load function. 

Specifies priority for change priority function. May not be 255 (E-tasks). 
Must be in range 10-249 (U-tasks). 

Set by system to actual priority of specified task, 
(reserved) 

Used only for START functions; specifies address at which to start specified 
task. If ZERO, signifies normal transfer address, as specified at TET/16 time. 

Time Type: indicates type of time delay. Used only for Delay-Start. Legal 
codes are: 

0000 = seconds since midnight 

0001 = milliseconds from now. 

Specifies number of seconds or milliseconds, as defined by TT field, to delay 
the start operation. Used only for Delay-Start. 

Specifies device affected by Connect, Thaw, SINT, Freeze and Unconnect 
functions. 

Specifies parameter to be queued for Queue parameter function; specifies 
device parameter for Connect functions. 

Specifies address of message buffer for Send Message function. 



34-37 



(Reserved) 
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APPENDIX 1 (Continued) 



JITS 00000000001 1 1 11 1 11 1 1222222222233 
12 3 4 5 6 7 8 9 01234567890123 4 5 6 7 8 9 1 
NAME I O I E I |L| |H| |m|Q|P| |o|t|i|f|U| 



m 



•x-r 



BIT(S) 



NAME 



HEX MASK 



MEANING 



0-1 



2-3 



4-5 

6 

7 

8 

9-10 

11 

12 

13 

14-15 

16 

17 

18 

19 

20 

21-24 
25 

26-28 
29-30 



31 



L 
H 

M 

Q 



O 

T 
I 
F 
U 



N 
A 



8000 0000 
COOO 0000 



0000 0000 

1000 0000 
2000 0000 
3000 0000 

OCOO 0000 
0200 0000 
0100 0000 
0080 0000 

0010 0000 
0008 0000 

0004 0000 



0000 
0000 
0000 
0000 
0000 



8000 
4000 
2000 
1000 
0800 



0000 0040 

0000 0000 
0000 0002 
0000 0004 
0000 0006 



Direction: 00,01 = illegal codes 

10 = other task 

11 =self 

End Task: 00 = no function 

requested 
1 = cancel 

10 = delete 

1 1 = delete 

Reserved 

Load Task 

Load only in TETed partition. 

Task resident 

Reserved 

Send Message 

Add parameter to specified task's Task Queue. 

Change priority of specified task. 

Reserved 

Connect specified device to specified task. 

Thaw: enable interrupts on specified device. 

SINT: Simulate interrupt on specified device. 

Freeze: disable interrupts on specified device. 

Unconnect: disconnect specified device from specified task. 

Reserved 

Task Non-resident 
Reserved 

Start task: 00 = no function requested 

01 = start immediately 

10 = delay start 

1 1 = delay start 
Reserved 
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SVC 6 Error Codes 



The format of the Error Status halfword is as follows: 



FIELD 



POS. PTR. 



7 8 



ERROR CODE 



15 



Code 
Dec (Hex) 

0(0) 
1(1) 

2(2) 

3(3) 

4(4) 

5(5) 

6(6) 

7(7) 

8(8) 

10(A) 

11(B) 

12(C) 

13(D) 

14(E) 

15(F) 

16(10) 

17(11) 

18(12) 

25(19) 

65(41) 

66(42) 

68(44) 

73(49) 

74(4A) 

75(4B) 

76(4C) 

129-192 

(8! -CO) 



Function 

All 
All 



L 

All but L 

P 

L 

A 

S 

A (delay) 

M 

Q 

0,T,I,F,U 

0,T,I,F,U 

O 

T,I,F,U 

L 

L 

I 

L 

L 

L 

L 

L 

L 

L 

L 



Meaning 

No errors; all requested functions complete. 
Syntax error in TASK ID field. Does not apply to self- 
directed calls. 
Illegal function code. 
Task already present. 
No such task in foreground. 
Invalid priority. 

Floating point not supported by SYSGEN. 
Specified task not dormant. 
Invalid start address. 
Invalid code in TT field. 
Message not sent, task unable to receive 
No queue, full queue, or entnvs disabled. 
No such device in system. 
Device named is not a connectable device. 
Device is busy, cannot connect. 
Device not connected to specified task. 
Invalid or unassigned Load LU. 
Qiecksum error. 
Device is not SINTable. 

Partition does not have sufficient number of LUs. 
Resident Library or Task Common not present. 
Invalid format on Loader Informafion Block. 
Partition not vacant. 
I/O error during Roll In/out 
Assign/close error during Roll In/out 
Partition does not exist. 
I/O error reading Load LU; error status is as 
returned by SVC 1 . 



Condition Code 
Unchanged 
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APPENDIX 1 (Continued) 



SVC 7 Parameter Block Fields 



Command/Modifier 



FIELD 






1 


2 


3 


4 


5 


6 


7 


8 


10 


11 12 


13 15 


A 





H 


N 


P 


C 


D 


T 


AP 


BM 


FT 



Bits 




Name 

A 
O 



N 
P 
C 
D 
T 



Hex Mask 

8000 
4000 

2000 

1000 
0800 
0400 
0200 
0100 



Description 

Allocate - requires file type (FT) modifier 
Assign - requires access privilege (AP) and 

buffer management (BM) modifiers 
Change Access Privilege — requires access 

privilege (AP) modifiers 
Rename — no modifiers 
Reprotect - no modifiers 
Close - no modifiers 
Delete - no modifiers 
Checkpoint - no modifiers 



Bits 0-7 all Zero = Fetch Attributes 



8-10 



AP 



11-12 



13-15 



BM 



FT 





Access Privileges 


0000 


SRO - Shared Read Only 


0020 


ERO - Exclusive Read Only 


0040 


SWO - Shared Write Only 


0060 


EWO - Exclusive Write Only 


0080 


SRW - Shared Read-Write 


OOAO 


SREW - Shared Read-Exclusive Write 


OOCO 


ERSW - Exclusive Read-Shared Write 


OOEO 


ERW - Exclusive Read-Write 




Buffer Management 


0000 


Default Buffer Management 


0008 


Unbuffered (Physical) 


0010 


Buffered (Logical) 


0018 


Reserved 




File Type 


0000 


Contiguous 


0001 


Reserved (considered illegal) 


0002 


Indexed 


0003 





0007 



Reserved (considered illegal) 
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SVC 7 Status Byte 

ERROR CODE 
DEC (HEX) 

0(00) 
1(01) 
2(02) 
3(03) 
4(04) 
5 (05) 
6(06) 
7(07) 
8(08) 
9(09) 

10 (OA) 

11 (OB) 

12 (OC) 

13 (OD) 
129-192 
(81 -CO) 



FUNCTION 



ALL 

A,0,D 

All but A,D 

A,0,D 

A,0,N,D 

A 

0,P,D 

All but C,T,F 

O 

All but A, O 

A,0,N.P,D 

A,0,N,D 

O 

C 

All but F 



APPENDIX 1 (Continued) 



MEANING 



No error, the requested functions are complete. 

Illegal function, illegal file type 

LU error; illegal LU 

Volume error; no such volume/device in system. 

Name error; mismatch on filename or extension field. 

Size error; erroneous LRECL or size field 

Protect error; erroneous protection Iceys. 

Privilege error; unable to obtain requested privilege. 

Buffer error; no room in system for file control blocks or buffers. 

Assignment error; LU not assigned. 

Type error; non-direct access device, or device off-line. 

File Descriptor error; illegal syntax. 

Attempt to assign SVC 6 connectable device. 

A Spool file was closed while the Spooler could not receive a message. | 

I/O error; interpreted as SVC 1 status byte. 



SVC 7 - FILE MANAGEMENT SERVICES 



FORMAT 



PARBLK 



CAL CODE 


ALIGN 


2 


DB 


CMD 


DB 


MOD 


DS 


1 


DB 


LU 


DB 


WKEY 


DB 


RKEY 


DC 


H'LRECL' 


DC 


C'VOLN' 


DC 


C'FILENAME' 


DC 


C'EXT' 


DC 


F'SIZE' 



0(0) 


1(1) 


CMD 


MOD 


2(2) 


3(3) 


STAT 


LU 


4(4) 


5(5) 


WKEY 


RKEY 


6(6) 


LRECL 


8(8) 


— VOLN 


12(c) 


— FILENAME — 


— — 


20(14) 

EXT 




23(12) 




RESERVED 


24(18) 


SIZE 
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SVC 7 REQUIRED FIELDS 



APPENDIX 1 (Continued) 



FUNCTION 


REQUIRED FIELDS 


















CMD 


AP 


BM 


FT 


LU 


KEYS LRECL 


VOLN 


FILEN 


EXT 


SIZE 


ALLOCATE 


^ 






v/ 




y 


y 


y 


y 


y 


y 


ASSIGN 


y 


y 


^y 




y 


y 




y 


y 


y 




CHANGE ACCESS PRIVILEGE 


v/ 


v/ 






y 














RENAME 


s/ 








y/ 








y 


y 




REPROTECT 


v^ 








V 


y 












CLOSE 


v/ 








y 














DELETE 


y 










y 




y 


y 


y 




CHECKPOINT 


V 








y 














FETCH ATTRIBUTES 


y 








y 

















SVC 9 - LOAD TSW 



No parameter block; SVC effective address specifies address of TSW to be loaded. 
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APPENDIX 2 
CONTROL BLOCK SUMMARY 

TASK STATUS WORD (TSW) 

Task Status Word is 32 Bits. First halfword (bits 0-15) contains status defined later. Second halfword (bits 16-31) contains 
the current location counter as in a PSW. 



Bit 


1 

2-3 
4 



8 

9 

10 
11 
12-15 



Hex Mask 
8000 

4000 



0800 



Name 
W 



0200 

0100 

0080 
0040 

0010 
OOOF 



O 

E 
CC 



Description 

Trap Wait-task suspended until a task 
trap occurs. 

Power Restoration Trap Enable -a task 
trap occurs on completion of system 
power restore sequence. 

Reserved-must be ZERO. 

Task Queue Service Trap Enable—a task 
trap occurs when an item is added to 
the Task Queue. Also a trap occurs if 
a TSW is loaded with this bit set and 
the Task Queue is not empty. 

Reserved-must be ZERO. 

Enable Task Queue entry on interrupt 
from a connected Trap Generating 
Device. 

Enable Task Queue entry on Queue 
Parameter (SVC 6) request directed 
at this task. 

Enable Task Queue entry on completion 
of a time interval. 

Enable Task Queue entry on completion 
of I/O Proceed request. 

Reserved— must be ZERO. 

Enable Task Queue entry on task message 

Condition Code (as in PSW). 



TASK OPTIONS BITS (TCB) 

Bit Hex Mask 

8000 



4000 
2000 
1000 
0800 
0400 



Meaning 

Executive Task (E-Task) if 1 
User Task (U-Task) if 

Arithmetic Fault Continue if 1 

Arithmetic Fault Pause if 

Task uses SPFP registers if 1 

Task does not use SPFP registers if 

Task is Memory Resident if 1 

Task is nonMemory Resident if 

Task uses old SVC 1 format if 1 

Task uses OS/ 16 MT2 SVC 1 format if 

Task is the background task if 1 

Task is a foreground task if 
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Bit 
6 



9 
10 



Hex Mask 
0200 

0100 

0040 
0020 



11-15 

TASK STATUS BITS (TCB) 



APPENDIX 2 (Continued) 
Meaning 



SVC 6 ignored (Background only) if 1 

SVC 6 illegal (Background only) if 

Task is reliable if 1 

Task is nonroUable if 

Reserved for system use 

Task uses DPFP registers if 1 

Task does not use DPFP registers if 

Program addresses 0-7FFF are mapped to physical 

memory 8000-FFFF if 1 , physical memory 

0-7 FFF if 2 (extended systems only"" 

Reserved for system use 



Bit 



1 

2 

3 

4 

5 

6 

7 

8 

9 

10 

11 

12 



Hex Mask 


Meaning 


8000 


Dormant 


4000 


I/O Wait 




Reserved 


1000 


Roll Wait 




Reserved 


0400 


Console Wait (PAUSEd) 


0200 


Time Wait 


0100 


Trap Wait 


0080 


SVC 2 Wait 


0040 


SVC 5/6 Wait 


0020 


SVC 7 Wait 




Reserved 


0008 


DCB Wait (File I/O Wait) 



User Dedicated Locations (UDL) 



U 101 




? !?■ 




CTOP 


COMBOT 


4 141 




6 (61 




UTOP 


UBQT 


B (81 


AITASKQI 




1DIAI 






POWER RESTORE OLD TSW SAVE AREA 


14(E1 






POWER RESTORE NEW TSW 


18(121 






TASK QUEUE SERVICE OLD TSW SAVE AREA 


22(16) 






TASK QUEUE SERVICE NEW TSW 


26(1 Al 




28(1CI 




AIMESSAGEBUFFERI 


RESERVED 


26(1 Al 






RESERVED 


,1S; l?4| 


SINGLE PRECISION 

FLOATING POINT REGISTER 

SAVE AREA 


68(441 


DOUBLE PRECISION 
FLOATING POINT REGISTER 
SAVE AREA 



A2-2 
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APPENDIX 3 
OS/16 MT2 DATA STRUCTURES 



For a listing of the OS/ 16 MT2 Data Structures copy the disc file PCB16.CAL or the magnetic tape file **PCBMT2 to 
a print device. 

Example: 

LD COPY 

AS 1,PCB16.CAL 

AS 2, PR: 

AS 5, CON: 

ST 

CPYA ,ALL 

END 

PCB16.CAL (**PCBMT2) have been defaulted for non-extended memory systems. If the user desires to reassemble 
the Driver Library source for extended memory systems, the following source update must be made. 

SELECT 

EXT EQU 1 PCB90001 

/* 
ENDUP 
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INDEX 



A (Abort Termination Routine), 9-4 

A (Busy) Flag, 9-4 

A (Initialize Routine), 9-5 

Access Methods, 6-4 

Access Privileges, 3-30 | 

Allocate, 3-31 

Allocation, 6-7 

ASCII Strings, 4-5 

Assign, 3-32 

Assignment, 6-8 

Attributes, 9-4 

Background Partition, 1-5 
Buffer Address, 3-5 
Buffer Management, 3-30, 6-4 
Buffered Logical , 6-5 
Busy Flag, 9-6 

CAL Assembler, 5-11 I 

Cancel I/O, 9-13 

Card Reader, 8-7 

Cassette, 8-10 

Qiange Access Priveleges, 3-32 . 

Checkpoint, 3-33 

Checkpointing, 6-8 

Qose, 3-33 

Closing, 6-8 

Code 1 - Pause, 3-8 

Code 2 - Get Storage, 3-8 

Code 3 - Release Storage, 3-9 

Code 4 - Set Status, 3-9 

Code 5 - Fetch Pointer, 3-9 

Code 6 - Unpack Binary Number, 3-10 

Code 7 - Log Message, 3-10 

Code 8 - Fetch Time, 3-1 1 

Code 9 - Fetch Date, 3-1 1 

Code 15 - Pack Numeric Data, 3-12 

Code 16 - Pack File Descriptor, 3-12 

Code 17 - Mnemonic Table Scan, 3-13 

Code 18 - Move ASCII Characters, 3-14 

Code 19 -Peek, 3-15 

Code 23 - Timer Management, 3-15 

Command, 3-30 

Command Function Requests, 3-4 

Command/Modifier, 3-28 

Command Processors, 4-1 

Command Processor Services, 1-4 

Command Statement Input, 4-1 

Conclusions, 6-9/6-10 | 

Connect, 3-24 

Contiguous Files, 1-11, 6-7, 8-1 | 

Contiguous File Structure, 6-7 

Control Block Summary A2-1 

Conversion Equipment, 8-13 
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INDEX (Continued) 

Data Management Services, 1-9 

Data Transfer Requests, 3-3 

Decimal and Hexadecimal Numbers, 4-3 

Definition of Terms, 6-1 

Delete, 3-33 

Deletion, 6-8 

Devices, 1-9 

I Device Code Example, 3-35/3-36 
Device Control Block, 9-1 
Device Control Block Map, 9-2 
Device Number, 9-4 
Digital Multiplexor, 8-13 
Direct Access Files, 1-9 
Driver Initialize Routine (DIR), 9-10 
Driver Logic Flow, 9-6 
Dynamic Protection, 1-14, 6-3 

Eight Line Interrupt Module, 8-12 

End Task Function, 3-23 

Errors, 3-20 

Error Status (Device Dependent and Device Independent Status), 3-4 

Establisli A Sample Overlayed Task, 7-3/7-4 

Example Device Codes, 3-35/3-36 

Executive Routines, 9-10 

Executive Services, 1-7 

Extension, 3-31 

Fetch Attributes, 3-33 
File Access Methods, 1-13 
File and Device Protection, 1-14 
File Descriptors, 4-4 
I File Identification, 1-10, 6-1 
Filename, 3-31 
File Management, 6-7 
File Organization, 1-11 
File Protection, 6-2 
File Structures, 6-5 
Flags, 9-4 

Floating Point and Fixed Point Divide Arithmetic Faults, 2-5 
Floppy Disc, 8-9 

Foreground/Background Tasks, 1-3 
Foreground Partitions, 1-5 
FORTRAN Source, 5-12 
FORTRAN Source with RTL, 5-12 
Freeze, 3-24 

Functional Descriptions, 8-1, 8-2, 8-3, 8-6, 8-7, 8-8, 8-9, 8-10, 8-1 1, 8-12, 8-13 
Further Mnemonics, 4-5 

Guide to OS/16MT2 File Structures, 6-1 

Guide to Task Handled Traps, 5-1 

Guide to User Overlays, 7-1 

Guide to Using SVC2 Facilities, 4-1 

Guide to Writing Drivers, 9-1 

HALT I/O, 9-13 

Halt I/O Command, 3-7 

High Speed Paper Tape Reader/Punch, 8-6 

Illegal Instruction, 2-5 
I Identification of Files, 1-10, 6-1 
Indexed Files, 1-11, 6-6, 8-2 
Indexed File Structure, 6-6 
Input/Output Programming, 8-1 
Internal Flow, 9-7 
Interrupts, 1-8, 2-5 
Interrupts and Traps, 1-8, 2-1 
Interrupt Service Routine (ISR), 9-11 
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Introduction to System Overview, 1-1 

lODONE, 9-12 

I/O Termination, 9-11 

I/O WAIT, 9-12 

I/O Wait Thread, 9-12 

Keys, 9-4 

Length of Data Transfer, 3-6 

Line Printer, 8-7 

Load Task Function, 3-23 

LOCAL CRT, 8-5 

Logical Record Length (LRECL), 3-31 

Logical Unit (LU), 3-4 

LU Field, 3-30 

Machine Malfunction, 2-6 
Mainline Code, 5-5 
Manual Organization, 1-3 
Maximum Record Length, 9-4 
Memory Management, 1-5 
Memory Protect Fault, 2-6 
Message Buffer Structures, 3-26, 3-27 
Mnemonic Scan, 4-1 
Moving Head Disc, 8-8 
Multiple Buffer Chain, 3-26 
Multiple Buffer Ring, 3-26 
Multiple LU Considerations, 6-3 

New Status, 9-5 

Null Device, 1-15/1-16 

Old PSW, 9-5 

OS/16 MT2 Data Structures, A3-1 

Operand Decoding, 4-3 

OS/16 MT2 File Structures, 1-12 

OS/16 MT2 Memory Map Example, 1-6 

OS/16 MT2 Supervisor Calls, 3-1 

OS/16 MT2 Symbols and Strucs, 5-8 

OS/16 MT2 System Overview - (Illustration of), 1-2 

Overlay Conventions, 7-2 

Overlay Design Considerations, 7-3/7-4 

Overlay Example, 7-3/7-4 

Partition for an Overlayed Task, 7-2 
Power Restoration, 1-8 
Power Restoration Traps, 2-5 
Power Restoration Trap Service Routine, 5-7 
Previously Written 16-bit Programs, 1-3 
Program Addresses and Logical Segments, 1-4 
Protection, 1-4, 1-7 
Protection Modification, 6-3 

Queue Parameter Function, 3-23 

Random Access, 1-13, 6-4 

Random Address, 3-6 

Read/Write Count, 9-4 

Registers on Entry to Driver, 9-15 

Registers on Entry to Executive, 9-15 

Register Save Area, 9-5 

Rename, 3-32 

Reprotect, 3-32 

Resident libraries, 1-5 

Resident Loaders, 1-7 

RoU Out/In, 1-7 

Root and Overlay Segments, 7-1 

RTOS Driver Compatibility with OS/ 16 MT2, 9-16 
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Sample Driver, 9-13 

Sample Memory Allocation, 1-6 

Send Message Function, 3-23 

Sending and Receiving Task Messages, 3-25 

Sequential Access, 1-14, 6-4 

Single Buffer Cliain, 3-26 

Single Buffer Ring, 3-26 

SINT, 3-24 

Size, 3-31 

Start Task Function, 3-25 

Static Protection, 1-14, 6-2 

Status, 1-4, 3-30 

Status Definition, 8-3, 8-4, 8-6, 8-7, 8-8, 8-9, 8-10, 8-11, 8-12, 8-13, 8-14 

Status Return, 3-20 

Summary of Register Connections, 9-15 

Supervisor Calls, 3-1, 9-9 

Supported Attributes, 8-1, 8-2, 8-3, 8-5, 8-6, 8-7, 8-8, 8-9, 8-10, 8-11, 8-12, 8-13 

Supported Devices, 8-1, 8-2, 8-3, 8-5, 8-6, 8-7, 8-8, 8-9, 8-10, 8-11, 8-12, 8-13 

SVC Errors, 3-2 

SVC Instructions, 3-1 

SVC Summary, AM 

SVC 1 Command Function Code, 3-4 

SVC 1 Data Transfer Function Code, 3-3 

SVC 1 Device Independent Status Byte, 3-5 

SVC 1 Input/Output Request, 3-2 

SVC 1 Parameter Block, 9-9 

SVC 2 Code 19 Parameter Block, 3-15 

SVC 2 - General Service Functions, 3-7 

SVC 3 - END OF TASK (EOT), 3-16 

SVC 5 - Fetch Overlay, 3-16 

SVC 6 Error Codes, 3-22 

SVC 6 Function Codes, 3-21 

SVC 6 - Intertask Coordination, 3-17 

SVC 6 Parameter Block, 3-18 

SVC 6 Parameter Block Fields, 3-19 

SVC 7 Command/Modifier Halfword, 3-29 

SVC 7 Device Attributes Halfword, 3-34 

SVC 7 - File Management Services, 3-28 

SVC 7 Functions, 3-31 

SVC 7 Parameter Block, 3-28 

SVC 7 Parameter Block Fields, 3-28 

SVC 7 Status Byte, 3-30 

SVC 9 - Load TSW, 3-35/3-36 

System Description, 1-3 

System Level, 7-3/7-4 

System Overview, 1-1 

System Space, 1-6 

Task Common, 1-5 

Task Handled Traps, 1-8, 2-4 

Task ID and Function Code, 3-19 

Test I/O Complete, 3-6 

Task Level, 7-3/7-4 

Task Management, 2-1 

Task Options, 2-6 

Task Overlays, 1-7 

Task Preparation, 5-11 

Task Priority and Scheduling, 1-9 

Task Queue, 5-5 

Task Queue Entry Types, 2-4 

Task Queue Items, 5-6 

Task Queue Service, 1-8 

Task Queue Service Routine, 5-6 

Task Queue Service Traps, 2-4 

Task Requirements Summary, 5-7 

Task Resident and Non-Resident Functions, 3-24 
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Task Status and Options, 2-6 

Task Status Bits, 2-7/2-8 

Task Status Halfword, 2-2 

Task Status Word (TSW) 1-8, 2-1, 5-L 5-2 

Task Structure, 5-1, 5-4 

Task Traps, 5-6 

Task Trap Service Routines, 5-6 

Tasks, 2-1 

Teletype, Keyboard Printer, 8-3 

Thaw, 3-24 

Time - Out Count, 9-4 

Tradeoffs, 6-8 

Trap Generating Devices (TGD), 2-5 

Trap Generating Device Functions, 3-24 

Unbuffered Physical, 6-5 

Unconditional Proceed, 3-6 

Unconnect, 3-24 

User Dedicated Locations (UDL), 2-2, 2-3, 5-3 

User Executive Tasks, 1-3 

Valid SVC Calls, 3-1 

Volume ID (VOLN) or Device Mnemonic, 3-31 

Volume Organization, 1-9, 1-10 

Wait Only, 3-6 
Wait/Proceed I/O, 3-6 
Write Key and Read Key, 3-30 
Write Protection, 1-15/1-16 

7 Track Magnetic Tape, 8-1 1 

9 Track Magnetic, 8-10 
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